QFX problem types

Every error answer of the QFX API under /v2 is a problem details object as RFC 9457 defines it, sent as application/problem+json. Its type is one of the URIs below, each of which leads to the page that documents it.

Handling a problem

Branch on the status code first, then on type. Never parse title or detail: what a client can act on has a member of its own.
Show detail to a person, or title when there is no detail, together with the entries of issues when there are any.
Quote instance to support: the gateway logs it with the request.
Send a request again after a 429 or a 503 once the seconds in Retry-After have passed. Do not retry a 501: what it refuses is switched off, not busy.
Ignore members you do not know. New members may be added to a type; a member never changes its meaning.

Members

Member	JSON type	Present	Meaning
`type`	string (URI)	always	Identifies the problem type: one of the URIs on this site, or about:blank. Branch on it; it never changes for a given problem.
`title`	string	always	A short summary of the problem type, in English, the same for every occurrence.
`status`	integer	always	The HTTP status code of the answer.
`detail`	string	when it applies	What went wrong in this occurrence, written to help correct the request. Show it to a person; never parse it.
`instance`	string (URI)	always	A urn:uuid that identifies this occurrence. Quote it to support: the gateway logs it with the request.
`parameters`	object	when it applies	The path parameters of the request under the specification's own names, for example collection-name and document-id. Present when the path has parameters.
`issues`	array	when it applies	One entry per problem found in the request (bad-request), or the path parameter that does not resolve (resource-not-found). An entry has type (an issue type URI; absent in a resource-not-found entry), title, detail, in (body, path, query or header), name (a JSON Pointer such as /metadata/INVOICE_DATE for the body, the parameter's name otherwise) and, for a path or query parameter, value: the value sent.
`requiredPermission`	object	when it applies	missing-permission: the resource and the action a permission would have to grant.
`hitLimit`	integer	when it applies	too-many-hits: the hit limit that applied.
`messageId`	string	when it applies	queue-message-not-replayable: the message the replay named.
`reason`	string	when it applies	queue-message-not-replayable: why the message cannot be replayed.
`limit`	integer	when it applies	payload-too-large: the largest request body accepted, in bytes.
`retryAfterSec`	integer	when it applies	too-many-requests, service-unavailable and storage-location-unavailable: the seconds to wait before sending the request again, the same as the Retry-After header.

Problem types

Type	Status	Title
`bad-request`	400	Bad Request
`no-access-token`	401	No Access Token
`invalid-access-token`	401	Invalid Access Token
`expired-access-token`	401	Expired Access Token
`missing-permission`	403	Missing Permission
`resource-not-found`	404	Resource Not Found
`operation-not-allowed`	405	This operation is not allowed on this deployment
`already-exists`	409	The resource already exists
`resource-in-use`	409	The resource is in use
`document-locked`	409	The document is locked
`document-on-legal-hold`	409	The document is on legal hold
`document-state-conflict`	409	The document's state does not allow this operation
`storage-location-locked`	409	The storage location is locked
`content-shared`	409	The stored content is shared with other documents
`import-state-conflict`	409	The import's state does not allow this operation
`administration-lockout`	409	The change would lock you out of administration
`built-in-protected`	409	Built-in roles and permissions cannot be changed this way
`confirmation-required`	409	The operation must be confirmed
`queue-message-not-replayable`	409	The message cannot be replayed
`collection-limit-reached`	409	No further collection can be created
`content-gone`	410	The document's content is no longer available
`payload-too-large`	413	Payload Too Large
`too-many-hits`	422	The search matches too many documents
`too-many-requests`	429	Too Many Requests
`internal-server-error`	500	Internal Server Error
`operation-disabled`	501	This operation is switched off for this deployment
`bad-gateway`	502	Bad Gateway
`content-integrity-failure`	502	The document's content does not match its SHA-256
`service-unavailable`	503	Service Unavailable
`storage-location-unavailable`	503	The storage location cannot be written to

Issue types

The entries of issues in a bad-request problem have one of these types.

Issue type	Title
`input-validation/schema-violation`	Input isn't valid with respect to schema
`input-validation/invalid-input`	Invalid input
`input-validation/referenced-resource-not-found`	Referenced resource not found

Problems without a type of their own

These answers carry the type about:blank, which RFC 9457 defines for a problem that means nothing beyond its status code; their title is the status code's own phrase.

Status	Title	When
405	Method Not Allowed	The path exists, but not with this method. Allow lists the methods it serves.
415	Unsupported Media Type	The request body's Content-Type is not one the operation accepts.

The paths without the /v2 prefix, the API of version 3.11.2, keep their own error answers: {"message": "..."} as plain text.