API errors · v1
Error codes
Every Partner API error is application/problem+json (RFC 9457) with a stable code. Its type is the page for that code, listed below. Branch on code, never on title or detail.
{
"type": "https://www.underwritinguk.ai/developers/errors/validation_failed",
"title": "Request validation failed",
"status": 422,
"code": "validation_failed",
"detail": "1 field is invalid.",
"request_id": "7b0b1e5c-2f7e-4a52-9a43-5b0d0f0e9d11",
"errors": [
{
"pointer": "/individuals/0/date_of_birth",
"code": "must_be_past",
"message": "Date of birth must be in the past."
}
]
}| HTTP | code | Title | Retry? |
|---|---|---|---|
| 400 | bad_request | Bad request | No |
| 400 | invalid_json | Request body is not valid JSON | No |
| 400 | idempotency_key_required | Idempotency-Key header required | No |
| 400 | invalid_scope | Requested scope not granted to this client | No |
| 401 | invalid_client | Client authentication failed | No |
| 401 | invalid_token | Access token is invalid | Refresh the token once |
| 401 | token_expired | Access token has expired | Refresh the token once |
| 402 | quota_exhausted | Token quota exhausted | No |
| 403 | insufficient_scope | Insufficient scope | No |
| 403 | module_not_enabled | Module not enabled | No |
| 403 | ip_not_allowed | IP address not allowed | No |
| 403 | organisation_suspended | Organisation suspended | No |
| 403 | acting_user_not_allowed | Acting user not allowed | No |
| 403 | forbidden | Forbidden | No |
| 404 | not_found | Resource not found | No |
| 405 | method_not_allowed | Method not allowed | No |
| 409 | case_exists | A case with this external_ref already exists | No (handle) |
| 409 | assessment_in_progress | An assessment is already running for this case | No (handle) |
| 409 | case_locked | Case is locked while an assessment is running | No (handle) |
| 409 | idempotency_conflict | Idempotency key reused with a different request | No (handle) |
| 409 | idempotency_in_progress | A request with this Idempotency-Key is still in progress | Yes, shortly, with the same key |
| 409 | idempotency_result_unavailable | The request was processed but its response cannot be returned | No (handle) |
| 409 | case_type_locked | case_type cannot change after the first assessment | No (handle) |
| 409 | assessment_cooldown | Assessment cooldown after a failed assessment | After Retry-After (≤ 5 min) |
| 409 | case_closed | The case is closed | No (handle) |
| 409 | conflict | Conflict | No (handle) |
| 412 | precondition_failed | Precondition failed | Re-read, then retry |
| 413 | payload_too_large | Payload too large | No |
| 415 | unsupported_media_type | Unsupported media type | No |
| 422 | validation_failed | Request validation failed | No |
| 422 | case_incomplete | Case is missing the minimum data | No |
| 422 | acting_user_not_found | Acting user not found | No |
| 429 | rate_limited | Rate limit exceeded | After Retry-After |
| 429 | concurrency_limited | Too many assessments running at once | After Retry-After |
| 500 | internal_error | Internal error | Yes, with backoff |
| 503 | service_unavailable | Service unavailable | Yes, after Retry-After |
| 503 | maintenance | Down for maintenance | Yes, after Retry-After |
The OAuth token endpoint answers OAuth 2.0 errors (invalid_client, invalid_scope, …), not problem+json. Within /v1 new codes may be added: treat an unknown code by its HTTP status. See the error catalogue (§15) and error handling and retries (§12.4) in the integration guide.