Errors

This page lists all error responses returned by the InfraRed API.

Envelope

All errors are returned in the following structure:

{
  "error": {
    "code": "string",
    "message": "string",
    "field": "string (optional)",
    "livemode": "boolean"
  }
}

Error Object Fields

Field	Type	Required	Description
`code`	string	✅	Machine-readable error code
`message`	string	✅	Human-readable explanation of the error
`field`	string	❌	Present for field-specific errors
`livemode`	boolean	✅	Indicates if the error occurred in live or sandbox mode

API Key Errors

Lists errors related to authentication and authorisation, specifically those involving invalid or mismatched API keys.
These usually occur when connecting to the API with incorrect or missing credentials.

Code	HTTP Status	Description
`api_key_environment_mismatch`	401 Unauthorized	API key environment does not match the requested environment.
`api_key_invalid`	401 Unauthorized	The provided API key is invalid.
`api_key_expired`	401 Unauthorized	The provided API key has expired.
`api_key_not_provided`	401 Unauthorized	No API key in Authorization header.

Common Errors

Lists general-purpose errors that may occur across multiple endpoints.
These include server issues, invalid parameters, rate limits, or incorrect resource identifiers.

Code	HTTP Status	Description
`internal_server_error`	500 Internal Server Error	Unexpected server error.
`request_limit_exceeded`	429 Too Many Requests	Rate limit exceeded.
`url_not_found`	404 Not Found	Requested URL not found.
`email_invalid`	400 Bad Request	Email value is invalid. Includes `field`.
`invalid_country_code`	400 Bad Request	Country code value is invalid. Includes `field`.
`date_invalid`	400 Bad Request	Date value is invalid. Includes `field`.
`date_time_invalid`	400 Bad Request	Datetime value is invalid. Includes `field`.

Field Validation Errors

Contains errors triggered by invalid or missing input data.
These errors occur when the request body fails validation checks, such as type mismatches or length constraints.

Code	Description
`field_value_type_invalid`	Field value type mismatch. Includes `field`.
`field_value_invalid`	Field value not in allowed set. Includes `field`.
`required_field_missing`	A required field is missing. Includes `field`.
`items_minimum_count_not_met`	Array has fewer than the minimum number of items. Includes `field`.
`field_minimum_length_not_met`	String shorter than minimum length. Includes `field`.
`field_minimum_value_not_met`	Number smaller than minimum value. Includes `field`.
`items_maximum_count_exceeded`	Array exceeds maximum number of items. Includes `field`.
`field_maximum_length_exceeded`	String exceeds maximum length. Includes `field`.
`field_maximum_value_exceeded`	Number exceeds maximum value. Includes `field`.

Request Errors

Lists errors related to request formatting, payload size, or idempotency.
These typically indicate that the client request was malformed or exceeded the API’s limits.

Code	HTTP Status	Description
`request_body_too_large`	413 Request Entity Too Large	Request payload size exceeds limit (2 MB).
`request_body_invalid_json`	400 Bad Request	Malformed JSON in request body.
`request_body_invalid`	400 Bad Request	Request body is invalid.
`request_idempotency_mismatch`	400 Bad Request	Idempotency key reused with a different body/params.
`service_temporary_unavailable`	503 Service Unavailable	Temporary service outage; try again later.

Document Information Extraction Errors

Details errors related to uploaded or linked documents, such as invalid file formats, payload encoding, or size violations.

Code	Description
`document_not_of_type`	Document type does not match expected type.
`document_base64_payload_invalid`	Base64 document payload is invalid. Includes `field`.
`document_url_unreachable`	Public URL of document is unreachable. Includes `field`.
`document_content_type_not_supported`	Unsupported document content type (only PDF, JPEG, PNG).
`document_too_large`	Document size exceeds maximum (20 MB).

Name Screening Errors

Lists errors related to name screening requests, which check names against watchlists or sanction lists.
These help identify issues with unavailable screenings.

Code	HTTP Status	Description
`name_screening_not_found`	404 Not Found	Name screening resource not found.