Errors
Every error comes back in one JSON format, with a code you can act on.
The error format
Errors use this shape:
{
"success": false,
"message": "API key has expired",
"errors": null,
"code": "API_KEY_EXPIRED"
}| Field | Meaning |
|---|---|
success | Always false for an error. |
message | A sentence you can show to a person or write to a log. |
errors | null, except on a 422, where it lists each invalid field and what is wrong with it. |
code | A 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.
| Code | Meaning | What to do |
|---|---|---|
API_KEY_MISSING | No Authorization: Bearer header. Message: "API key not provided". | Send the key as a bearer token. |
API_KEY_INVALID | The 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_EXPIRED | The 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.
| Status | When | Message |
|---|---|---|
| 403 | The 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. |
| 403 | The key is pinned to a different organization. | "This API key is not valid for the requested tenant." |
| 403 | The request comes from an address that is not on the key's allowed list. | "Source IP not allowed for this API key." |
| 403 | An organization or user key was sent without X-Tenant-ID. | "This API key requires an X-Tenant-ID header." |
| 403 | External 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." |
| 403 | Your role does not allow the action. A scope does not replace role permissions. | Varies by endpoint. |
| 404 | The 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. |
| 422 | The request failed validation. | "Unable to save. Please check the highlighted fields". errors lists each field. |
| 500 | An 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:
{
"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.