Error Handling
HTTP status codes, error response format, and retry strategies for the FRITH API.
Error response format
All error responses follow a consistent JSON structure:
{
"error": {
"code": "VALIDATION_ERROR", // Machine-readable code
"message": "title is required", // Human-readable message
"requestId": "req_01j2abc123", // Use in support tickets
"errors": [ // Field-level errors (422/400)
{ "field": "title", "message": "Required" }
]
}
}
Status code reference
| Code | Name | Retryable | Description |
|---|---|---|---|
| 200 | OK | — | Request succeeded. |
| 201 | Created | — | Resource created successfully (POST). |
| 400 | Bad Request | — | Request body is malformed or missing required fields. Check the errors array in the response. |
| 401 | Unauthorised | — | API key is missing, invalid, or revoked. Regenerate the key and update your integration. |
| 403 | Forbidden | — | The API key does not have permission for this action. Use a key with higher permission level. |
| 404 | Not Found | — | Resource does not exist or belongs to a different organisation. Check the ID and the authenticated organisation. |
| 409 | Conflict | — | Resource already exists (e.g. duplicate matter reference). Resolve the conflict before retrying. |
| 422 | Unprocessable Entity | — | Request is well-formed but contains invalid values (e.g. invalid date, unsupported enum value). See errors array. |
| 429 | Too Many Requests | Rate limit exceeded. Wait Retry-After seconds before retrying. Implement exponential backoff. | |
| 500 | Internal Server Error | FRITH server error. Retry after a brief delay. If the error persists, contact developer@getfrith.com with the request ID. | |
| 503 | Service Unavailable | FRITH is temporarily unavailable (maintenance or incident). Check status.getfrith.com and retry with backoff. |
Retry strategy
- Only retry on 429 (rate limit) and 5xx (server error) responses — 4xx errors will not succeed on retry without fixing the request.
- Use exponential backoff with jitter: base delay 1s, max delay 60s, up to 5 retries.
- For 429: respect the Retry-After header if present — wait at least that many seconds.
- Include the requestId from the error response when contacting developer@getfrith.com about persistent 500 errors.
- Idempotent requests (GET, PUT, PATCH): safe to retry. Non-idempotent requests (POST): use an Idempotency-Key header to prevent duplicate creation.
Idempotency
For POST requests that create resources, include an Idempotency-Key header with a unique UUID. If the same key is used within 24 hours, FRITH returns the original response without creating a duplicate — safe to retry on network failure:
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000