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. |
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. |
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, or the offset-style page — v1 paginates by cursor. |
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 X-Active-Profile header names a company that does not exist or does not belong to the accounting-firm tree of the authenticated key. Both cases answer the same so that the API never reveals companies of other tenants. |
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. |
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, or a path from a different area of the API. |
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.