Request error codes
Every public API error code emitted by Request, with its HTTP status, its type and a page per code.
Error codes emitted by Request. Each code links to its own page with the cause and the action to take.
| Code | Type | HTTP | Description |
|---|---|---|---|
business_rule_violation | invalid_request_error | 422 | A domain invariant rejected the operation. This code carries the family; error.subcode names the concrete rule and error.message explains it. |
conflicting_pagination_params | invalid_request_error | 422 | starting_after and ending_before travelled in the same request. They walk the collection in opposite directions, so only one of them can apply. |
external_id_already_exists | conflict_error | 409 | The external_id you use to reconcile with your own system is already assigned to another object of the same type in this company. |
invalid_param_format | invalid_request_error | 422 | A legacy form request rejected the shape of a value. Migrated endpoints report the same situation as parameter_invalid_format or parameter_invalid_integer. |
invalid_param_value | invalid_request_error | 422 | A legacy form request rejected the value of a field. Migrated endpoints report the same situation as parameter_invalid_enum or parameter_invalid_range. |
invalid_status_transition | invalid_request_error | 422 | The requested state is not reachable from the state the document is in right now. |
length_required | invalid_request_error | 411 | A request with a body arrived using chunked transfer encoding, without declaring its size. The API needs the length up front to reject oversized payloads before buffering them. |
metadata_too_many_keys | invalid_request_error | 422 | The metadata object exceeds the limit of 50 keys per resource. |
metadata_value_too_long | invalid_request_error | 422 | One value of metadata exceeds 500 characters once serialised to text. |
method_not_allowed | invalid_request_error | 405 | The path exists but does not accept the HTTP verb used. |
missing_required_param | invalid_request_error | 422 | A legacy form request found a required field missing. Endpoints already migrated to the canonical parsers report the same situation as parameter_missing. It is also returned for an invoice, quote, proforma, delivery note or recurring invoice line sent without tax_rate when neither its product has an assigned tax nor your company has a default VAT for that document type: error.param is lines.N.tax_rate and error.line_index is the zero-based position of that line. POST /v1/companies/{company}/invoices also returns it when you ask for the email sending (options.send_automatically) and there is no possible recipient — no client, or a client with no email, and no options.send_to: error.param is options.send_to and no invoice is created. |
parameter_invalid | invalid_request_error | 422 | A value object built from the payload rejected the value it received. error.subcode names which one — tax code, country code, rate, and so on. |
parameter_invalid_boolean | invalid_request_error | 400 | A parameter that must be a boolean received a value outside the accepted representations (true/false, 1/0). |
parameter_invalid_cursor | invalid_request_error | 400 | The starting_after or ending_before cursor is not a valid UUID, so it cannot point at any row of the collection. |
parameter_invalid_empty | invalid_request_error | 400 | A parameter arrived with an empty value: an in filter with no items, a comparison with nothing after the operator, or an equality filter with an empty string. |
parameter_invalid_enum | invalid_request_error | 400 | The value falls outside the closed set the parameter accepts. On listings it also covers a filter operator other than eq, gte, lte, gt, lt, in or contains, and it is the main code (400). On operations that validate a form or a query parameter with rules (for example format on the invoice PDFs) it arrives as an entry of error.errors[], with its allowed_values, inside a 422 invalid_param_value. |
parameter_invalid_format | invalid_request_error | 400 | The value has the right type but not the shape the parameter requires: a date, an identifier pattern or a header such as Factuarea-Version. |
parameter_invalid_integer | invalid_request_error | 400 | A parameter that must be a whole number received something that cannot be parsed as one, such as limit=abc. |
parameter_invalid_iso8601 | invalid_request_error | 400 | A range filter (gte, lte, gt, lt) received a value that is neither numeric nor an ISO 8601 date. |
parameter_invalid_range | invalid_request_error | 400 | A numeric parameter fell outside its accepted bounds. The usual case is limit, which must be between 1 and 100. |
parameter_invalid_string | invalid_request_error | 400 | A parameter that must be text received an array, an object or a value that cannot be read as a string. |
parameter_invalid_url | invalid_request_error | 400 | A field that must hold an absolute URL received a value that is not one, usually because the scheme or the host is missing. |
parameter_invalid_uuid | invalid_request_error | 400 | An identifier field received a value that is not a valid UUID. Every v1 resource id is a UUID. |
parameter_invalid_value | invalid_request_error | 422 | The value is syntactically correct but not admissible for this resource: outside the canonical catalogue of the field, or inconsistent with the rest of the payload. |
parameter_missing | invalid_request_error | 400 | The endpoint requires a parameter that the request did not carry. error.param names it. |
parameter_unknown | invalid_request_error | 400 | The request carries a parameter the endpoint does not accept: a filter outside its allowlist, a sort field that is not sortable, the offset-style page — v1 paginates by cursor — or a header that has been retired from v1. |
payload_too_large | invalid_request_error | 413 | The request body exceeds the accepted size: 1 MB as a rule, 6 MB on the endpoints that accept files. |
profile_not_found | not_found_error | 404 | The {company} path segment names a company that does not exist or is not within the credential's NIF scope. Both cases answer the same so that the API never reveals companies of other accounts. |
resource_already_exists | conflict_error | 409 | Creating the object would duplicate one that already exists under a unique key — tax id, SKU, external id. error.details.existing_resource_id points at the object that already holds the value. |
resource_conflict | conflict_error | 409 | The operation collided with the current state of the resource and no more specific conflict code applies. |
resource_immutable | invalid_request_error | 422 | The object is closed to changes for this operation: its state or its accounting record forbids modifying it. |
resource_locked | conflict_error | 409 | Another operation holds the resource until it finishes: concurrent writes on the same object are serialised instead of interleaved. On POST /v1/companies/{company}/invoices with external_id, another request with the SAME external_id is still in progress and had not finished after waiting 20 seconds. |
resource_not_deletable | invalid_request_error | 422 | The object exists but its state or its dependants block the deletion. In bulk deletions this is the per-row code of every entry that could not be removed. |
resource_not_found | not_found_error | 404 | The identifier resolves to nothing visible to the authenticated company. Objects belonging to another company answer exactly the same way, by design. |
route_not_found | not_found_error | 404 | The path does not match any v1 endpoint. It is usually a typo, a missing /v1 prefix, a path from a different area of the API, or the flat form of a route that the breaking window moved under the company or account segment; in that last case error.subcode is legacy_route_moved. |
unknown_filter | invalid_request_error | 422 | A listing received a filter it does not know. The canonical v1 parsers report this as parameter_unknown; this code survives for endpoints that have not migrated yet. |
unsupported_api_version | invalid_request_error | 400 | The Factuarea-Version header is well formed but names a version outside the supported set. |
unsupported_media_type | invalid_request_error | 415 | A request with a body declared a Content-Type other than application/json. |
Related
Error codes by category
Find an error by the category that emits it.
Full reference table
All codes, HTTP statuses, types and descriptions in one reference.
Error model
Interpret the error envelope and handle errors by code.