Error codes

Unfortunately, API requests sometimes don't go as planned. This page describes the HTTP status codes Inspectorio APIs return, the format of error responses, and how your API client should retry.

HTTP status codes

Status	Meaning	What to do
400	Bad request: the request is malformed or a value is invalid.	Fix the request. Do not retry it unchanged.
401	Authentication error: the apiKey header is missing, or the key is invalid or removed.	Check the key. See Authentication.
403	Forbidden: your organization does not have access to this resource or action.	Check the permissions and data-sharing settings of your organization.
404	Not found: the URL is wrong, or the record does not exist or is not visible to your organization.	Check the base URL, path, and identifiers.
409	Conflict: the request conflicts with the current state, such as a duplicate identifier or a record that is in use.	Read the error message, resolve the conflict, then retry.
422	Validation error: one or more fields failed validation.	Read the errors object, fix the fields, and resend.
429	Too many requests: you exceeded the rate limit.	Retry later with backoff. See Retrying requests.
500	Internal system error.	Retry with backoff.
502	Bad gateway.	Retry with backoff.
503	Service unavailable.	Retry with backoff.
504	Gateway timeout.	Retry with backoff.

Error response format

Most endpoints return errors as a JSON object with an errorCode and a human-readable message:

{
  "errorCode": "Generic",
  "message": "Bad Request"
}

Validation errors (422) and internal errors (500) can also include an errors object, keyed by the field or area that failed:

{
  "errorCode": "Generic",
  "message": "Validation error",
  "errors": {
    "type": ["Input type is not valid"]
  }
}

note

Some newer endpoints use a different error body. For example, they return a detail field with an optional machine-readable code. The Responses section of each endpoint in the API reference shows the exact error format for that endpoint.

Retrying requests

As you build your API client, add retry logic for temporary errors: 429, 500, 502, 503, and 504.

We recommend this schedule:

1. Retry the request after 1 minute.
2. If it fails again, retry after 3 minutes.
3. If this attempt also fails, stop and try again during the next business day. Store the request information and mark it as "try again tomorrow".

For 429 responses, reduce the number of parallel requests (see Concurrency). If the response includes a Retry-After header, wait at least that number of seconds before retrying.

Do not retry 400, 401, 403, 404, 409, or 422 errors unchanged. They will fail again until the request is fixed.

Troubleshooting

Use the Integration Center to review your requests and their results. If an error persists, contact [email protected] with the endpoint, the time of the request, and the response body.