HTTP response codes

Our APIs use conventional HTTP responses to signal whether a request succeeded or failed. Responses with a 2xx status indicate success, 4xx statuses indicate failures caused by problems in the information you sent, and 5xx statuses indicate failures caused by internal or infrastructure problems.

TIP

The table below lists the HTTP response codes used in our APIs:

HTTP code	Description
200 OK	Your request was processed successfully.
201 Created	The request succeeded and a resource was created as a result.
400 Bad Request	Returned only by internal administrative routes, outside the scope of this documentation. In normal API use, you will not receive this code.
401 Unauthorized	The API key is missing, is invalid, or has no permission for the requested resource.
404 Not Found	The requested endpoint or object does not exist.
413 Payload Too Large	A file sent as multipart/form-data exceeds the maximum accepted size. See the values in Limits.
415 Unsupported Media Type	The request's Content-Type header is missing or unsupported. This code has nothing to do with the format of the file you sent, which is validated with code 422.
422 Unprocessable Entity	This is the most common error in our APIs. It happens when a required parameter is missing, when the value sent is invalid (for example, a CPF — the Brazilian individual taxpayer number — that fails check-digit validation), when the file format is not accepted, or when too many files are sent. The response message tells you which case it is.
500 Internal Server Error	An unexpected failure occurred on our servers. For security reasons, the details are obfuscated.

🚧 Attention!

Code 200 does not mean a positive result — it does not mean, for instance, that a document was found during classification. It only means the analysis completed without internal errors. To find out which information could be extracted, look directly at the corresponding field in the response object.

Error response format

Errors raised by the application follow the format below:

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid Federal Revenue Number"
  }
}

Field	Description	Type
id	Unique identifier of the request. Provide it when contacting support.	String
error.statusCode	The same HTTP code as the response.	Number
error.error	Name of the HTTP error.	String
error.message	Description of what prevented the processing.	String

WARNING

Errors handled by the infrastructure rather than by the application may arrive in a different format and without the id in the body. That is the case of a non-existent route and of a request body above the accepted limit, rejected before the identifier is generated. In these cases, the request identifier is in the Nextid-ReqId header, present in every response.

TIP

The id is the fastest way for us to investigate a specific case. Keep it in your logs.

Billing

The HTTP code of the response determines whether the request is charged. See API billing.