Errors

Most API errors return a JSON body with an errors array. One endpoint category is the exception — read the note on 404 below before you write a generic error parser.

Error response format

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

For validation errors on write requests, the errors array contains one message per failing field:

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

The 404 exception

Every “record not found” response (id doesn’t exist, or belongs to a different organization) is raised explicitly in each controller’s rescue block, and it uses a singular error key with a string value — not the errors array used everywhere else:

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

If your error-handling code only checks body.errors, it will silently miss 404s. Check the status code first, and branch on the key when reading 404 bodies specifically.

HTTP status codes

Status	Meaning	Common causes
200 OK	Request succeeded	GET, PATCH
201 Created	Resource created	POST
204 No Content	Resource deleted	DELETE
401 Unauthorized	Token missing/invalid, or the request is valid but not authorized	Both cases share this status — see Authentication for how to tell them apart. An organization_id that doesn’t exist gets the authorization failure too, as an organization you cannot reach. There is no 403 in this API
404 Not Found	Resource not found	Wrong ID, or resource belongs to a different organization. Body uses the singular error key — see above
422 Unprocessable Entity	Validation failed	Required fields missing, invalid field values
429 Too Many Requests	Rate limit exceeded	See Rate limits

400 Bad Request and 500 Internal Server Error can occur (malformed JSON, unexpected server errors) but aren’t explicitly handled by the API controllers — don’t assume their response body follows the errors/error shape above.

Handling errors

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()

Related articles

• Getting started
• Concepts
• Authentication
• Rate limits
• Changelog