Errors

The API returns each error with the HTTP status and a body in the RFC 9457 format. The content type is application/problem+json.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The call did not include a valid API key. Send the key in the Authorization header, in the format Bearer <key>.",
  "code": "unauthorized"
}

Fields

Field	What it contains
`type`	Always `about:blank`.
`title`	The phrase of the HTTP status, in English.
`status`	The HTTP status.
`detail`	The explanation of the error, in the language of the organization. The text can change.
`code`	The error code, in English. The code does not change in v1.

Use the code to decide what your system does. Show the detail to a person.

The language of the explanation

The detail and the message follow the language that the organization chose in QX: Portuguese (pt-BR) or English (en). The API knows the organization from the key. For that reason, the answers that leave before the key stay in Portuguese:

the call without a valid key (401) and the IP address with too many invalid keys (429 too_many_invalid_keys);
the errors that the API answers before it reaches the endpoint, such as route_not_found, method_not_allowed, not_acceptable and the malformed_request of a path or a query that the API cannot read.

The code, the title and the field names are always in English. A replay with the same Idempotency-Key returns the stored answer in the language of the first call.

Validation error

The 422 response with the code validation_failed also has the errors list, with one item for each field with an error. The other 422 codes have one cause only, which the code already names, and they do not have the list.

Field	What it contains
`field`	The name of the field.
`code`	The error code of the field, in English.
`message`	The explanation of the field error, in the language of the organization.

Request outside the contract

The API checks each request against the OpenAPI specification of this documentation. The check runs after the checks of the key, the subscription, the plan and the call limit. A refused request does not use a paid write. The API does not keep its response for the Idempotency-Key.

What is outside the contract	Response
A parameter of the query, of the path or of a header	`400` with the code `invalid_parameter`. The `detail` names the parameter.
A value of the body	`422` with the code `validation_failed`. The `errors` list has one item for each field.
The whole body or the content type	`400` with the code `malformed_request`.

The field of a field inside another field uses a dot, such as recipient.email. A body that is not an object appears as body. The code of the field follows this table:

`code`	When
`blank`	A required field is missing, or a list or an object is empty.
`unknown`	The field does not exist in the contract.
`invalid`	The value has the wrong type, the wrong format or the wrong value. For example, a number where the contract asks for text.

Some rules do not fit in the contract, such as “send the contact_id or the tax_id”. The API checks these rules after the contract. So a request with both kinds of error gets the contract errors first.

A call that the API cannot read

The 400 response with the code malformed_request tells that the API could not read the call. Examples of causes:

the path or the query has an invalid encoding;
the query repeats a parameter in different forms, such as limit=1&limit[]=2;
the body is not valid JSON;
the content type is not one of the types that the endpoint accepts, such as text/plain in a POST that receives JSON;
the address in the Client-IP header is not in the X-Forwarded-For header.

Codes

Status	`code`	What to do
400	`invalid_parameter`	Correct the parameter that the `detail` names.
400	`malformed_request`	Check the path, the query, the body and the headers. The section “A call that the API cannot read” gives examples of causes.
401	`unauthorized`	Check the key and the `Authorization` header.
402	`subscription_blocked`	Settle the subscription in QX.
402	`trial_limit_reached`	Subscribe to a plan in QX. The organization on trial reached the document limit of the trial.
403	`organization_archived`	Talk to QX.
403	`plan_required`	Subscribe to a paid plan in QX.
404	`not_found`	Check the id. An id of another organization also gets `404`.
404	`route_not_found`	Check the path and the HTTP method. The API does not have the path, or the path does not accept the method.
405	`method_not_allowed`	Use an HTTP method that this documentation shows. The API does not recognize the method of the call.
406	`not_acceptable`	Check the `Content-Type` and `Accept` headers. The API does not recognize the content type of the call.
409	`contact_exists`	Use the contact in the `contact` field. The organization already has a contact with this CPF or CNPJ.
409	`idempotency_key_in_use`	Wait a few seconds and repeat the call with the same `Idempotency-Key`. See Idempotency.
409	`document_has_content`	Check the document in QX. The Triage document already has a file or an answer, and the API swaps the file only on a collection document.
409	`document_locked`	Check the document in QX. The document is approved or discarded, or its collection does not accept documents.
409	`document_replaced`	Use the id in the `replaced_by` field. The document is a previous version, and the field contains the id of the current document.
409	`stale`	Call again. If the call included an `Idempotency-Key`, use a new value, because the API keeps this response. The data changed during the call. The call created no document and no collection. See Idempotency.
413	`file_too_large`	Send a smaller file. The limit is 25 MB, and 10 MB for a type without a file field.
422	`validation_failed`	Correct the fields in the `errors` list.
422	`contact_not_found`	Create the contact with `POST /contacts` and repeat the call.
422	`contact_archived`	Restore the contact in QX, or use another contact.
422	`pack_unavailable`	Choose an active pack. The `active` field of `GET /packs` shows an active pack.
422	`pack_not_for_contact`	Choose a pack that serves the type of the contact. The `required_for` field of the pack shows the type.
422	`no_email`	Add the email of the contact in QX, or create the collection with `send_invitation` equal to `false`.
422	`shareholder_tree_too_large`	Talk to QX. The pack asks for a document from each shareholder. The shareholder tree of the contact has more than 200 people and companies. The tree includes the contact.
422	`contact_mismatch`	Send the document of the collection’s contact, or send the document without `collection_id`.
422	`collection_not_accepting`	Choose an open collection. The collection is canceled, archived or with the partner, or it has no contact yet.
422	`document_type_inactive`	Choose an active document type.
422	`document_type_without_file`	Choose a type that accepts a file. The type is a form without a file field.
422	`unsupported_file`	Send the file in a format that the type accepts. A type without a file field accepts only PDF, JPEG and PNG.
422	`unknown_field`	Use the `key` of a field that `GET /documents/{id}` shows.
422	`idempotency_key_reused`	Use a new `Idempotency-Key` value for the new write. See Idempotency.
429	`rate_limited`	Wait for the seconds in the `Retry-After` header.
429	`daily_limit_reached`	Wait for the seconds in the `Retry-After` header. The limit resets at midnight, in the time zone of the organization.
429	`too_many_invalid_keys`	Correct the key and wait for the seconds in the `Retry-After` header.
other 4xx	`request_refused`	Talk to QX. The API could not complete the call.
503	`storage_unavailable`	Repeat the call in a few seconds, with the same `Idempotency-Key`. QX did not store the file, and the API created no document.
5xx	`internal_error`	Repeat the call in a few seconds. On a write that accepts the `Idempotency-Key`, repeat the call with the same value. See Idempotency. If the error continues, talk to QX. QX had an internal error.

Getting started

Reference

Fields

The language of the explanation

Validation error

Request outside the contract

A call that the API cannot read

Codes

​Fields

​The language of the explanation

​Validation error

​Request outside the contract

​A call that the API cannot read

​Codes

Fields

The language of the explanation

Validation error

Request outside the contract

A call that the API cannot read

Codes