Errors and rate limits

The v1 API uses standard HTTP status codes and a consistent JSON error body. Read this page when you are building error handling, retries, or backoff into an integration.

Error responses

When a request fails, the API returns a JSON body with a single detail field that describes the problem:

{
  "detail": "inspection not found"
}

The status code tells you the error class:

Treat the detail value as a diagnostic for your logs. Do not surface it as copy in your own UI.

Validation errors

A 422 reports schema validation failures and uses a different body shape. The detail field is an array, with one entry per problem. Each entry names the location of the bad value in loc, a human-readable message in msg, and a machine error type in type:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Use loc to map the error back to the field you sent. The first element is usually body, query, or path, followed by the field name. An entry can also carry an input value and a ctx object with extra context for some validation types.

Rate limits

The v1 service surface allows 300 requests per minute, counted per API key. The window is a fixed 60 seconds, so the count resets at the start of each window rather than rolling continuously.

When you exceed the limit, the API returns 429 with a detail of rate limit exceeded. No Retry-After or rate-limit headers are returned, so back off on your own and retry after the current 60-second window expires. Spread bulk operations over time rather than sending them in a burst.

AI features (for example template editing, report generation, and vision extraction) are not part of the v1 machine API and reject an API key with 403, so their separate per-user and per-org AI limits do not apply to your integration.

Pagination

The locations list supports paging through the limit and offset query parameters on GET /v1/locations:

Page through a large result set by requesting a fixed limit and increasing offset by that amount on each call:

GET /v1/locations?limit=100&offset=0
GET /v1/locations?limit=100&offset=100

Stop paging when a response returns fewer rows than your limit. Other list endpoints return their full result set and do not take limit or offset.

Handling errors

Handle each error class by its cause:

• On 401, check that your key is valid, sent as Authorization: Bearer <key>, not revoked, and not expired. See Authentication.
• On 403, the key is valid but lacks access to that resource or action. Re-fetch from a resource your key can see, or use a key with the right access.
• On 404, confirm the ID belongs to your organization and still exists before retrying.
• On 409, read the detail value to understand the conflicting state, then re-fetch the resource and adjust your request before retrying.
• On 422, fix the field named in loc and resend.
• On 429, back off until the current 60-second window expires, then retry. Spread bulk operations over time rather than sending them in a burst.
• On 500 or 503, retry with exponential backoff. A 503 means a server-side dependency is briefly unavailable, so a later retry usually succeeds.

See also

• Authentication
• Webhooks