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. |