Errors

Every error comes back in one JSON format, with a code you can act on.

The error format

Errors use this shape:

JSON
{
  "success": false,
  "message": "API key has expired",
  "errors": null,
  "code": "API_KEY_EXPIRED"
}
FieldMeaning
successAlways false for an error.
messageA sentence you can show to a person or write to a log.
errorsnull, except on a 422, where it lists each invalid field and what is wrong with it.
codeA machine-readable code for the errors listed below. It is an empty string when the error has no code. Use the HTTP status when code is empty.

A successful response has success: true, a message and data. A paginated list has success, data and meta.

Error codes

These three codes come from the API key check. All three are HTTP 401.

CodeMeaningWhat to do
API_KEY_MISSINGNo Authorization: Bearer header. Message: "API key not provided".Send the key as a bearer token.
API_KEY_INVALIDThe key was not found, or it is not an API key. With an X-Tenant-ID the message is "Invalid API key for tenant <id>. Check the key belongs to this organization." Without one, it says organization and user keys must send X-Tenant-ID.Check the key and the organization ID. Create a new key if the old one was revoked.
API_KEY_EXPIREDThe key is past its expiry date. Message: "API key has expired".Create a new key in Settings → API Keys.

One more code is returned when the rate limit is exceeded: RATE_LIMITED (HTTP 429). See Rate limits.

Other responses

These responses use the same format, and code is empty.

StatusWhenMessage
403The key lacks the scope the endpoint needs."You don't have permission to access this endpoint. This API key is missing the 'assignments:read' scope." The message names the scope that is missing.
403The key is pinned to a different organization."This API key is not valid for the requested tenant."
403The request comes from an address that is not on the key's allowed list."Source IP not allowed for this API key."
403An organization or user key was sent without X-Tenant-ID."This API key requires an X-Tenant-ID header."
403External API access is switched off, for the whole platform or for your organization."External API access is currently disabled." For one organization, the message adds "Please contact fido administrator to enable access."
403Your role does not allow the action. A scope does not replace role permissions.Varies by endpoint.
404The route does not exist, or the request went to a host other than api.fetchfido.ai."The requested resource could not be found." or a short status text.
422The request failed validation."Unable to save. Please check the highlighted fields". errors lists each field.
500An unexpected error on Fido's side.Typically "An unexpected error occurred — please try again." Retry once. If it repeats, report the request.

A 422 looks like this:

JSON
{
  "success": false,
  "message": "Unable to save. Please check the highlighted fields",
  "errors": {
    "name": ["The name field is required."]
  },
  "code": ""
}

The wording of a field message comes from the endpoint, so the example is only the shape.

For limits and the 429 response, see Rate limits.