エラー

ほとんどのAPIエラーは、errors配列を含むJSON本文を返します。例外があるため、汎用パーサーを作成する前に、下記の404の注意事項を確認してください。

エラーレスポンスの形式

{
  "errors": ["Description of what went wrong"]
}

書込みの検証エラーでは、失敗した項目ごとに1つのメッセージが配列に入ります。

{
  "errors": [
    "Name can't be blank",
    "Quantity must be greater than 0"
  ]
}

404の例外

IDが存在しない、または別の組織に属する場合の「レコードが見つからない」レスポンスは、各コントローラのrescue処理で明示的に発生します。ほかのエラーのerrors配列ではなく、文字列を値とする単数形のerrorキーを使います。

{
  "error": "Couldn't find Part with 'id'=999"
}

body.errorsだけを確認すると、404を見落とします。最初にステータスを確認し、404の本文を読むときはキーによって処理を分けてください。

HTTPステータスコード

ステータス	意味	主な原因
200 OK	リクエスト成功	GET、PATCH
201 Created	リソース作成	POST
204 No Content	リソース削除	DELETE
401 Unauthorized	トークンが未指定・無効、または有効でも操作権限がない	どちらも同じステータス。認証で区別する方法を確認してください。存在しないorganization_idも、アクセスできない組織と同じく権限不足になります。このAPIに403はありません。
404 Not Found	リソースが見つからない	IDが誤っている、または別の組織に属する。本文は単数形のerrorキー。上記を参照。
422 Unprocessable Entity	検証失敗	必須項目の未指定、無効な値。
429 Too Many Requests	レート制限超過	レート制限を参照。

不正なJSONや予期しないサーバーエラーによって400 Bad Requestや500 Internal Server Errorになる場合がありますが、APIコントローラは明示的に処理していません。本文が上記のerrorsまたはerror形式とは限りません。

エラーの処理

import requests

response = requests.get(
    "https://api.toolingmetrics.com/v1/organizations/12/machines",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)

if response.status_code == 401:
    print("Check your API token, or your role for this resource")
elif response.status_code == 404:
    print("Not found:", response.json().get("error"))
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", 60)
    print(f"Rate limited. Retry after {retry_after} seconds.")
elif not response.ok:
    errors = response.json().get("errors", [])
    print("API error:", errors)
else:
    data = response.json()

関連記事

• 入門
• 基本概念
• 認証
• レート制限
• 変更履歴