Errors

No 4xx or 5xx response uses a credit or generates overage charges.

Error format

Every error comes as JSON with error and, in most cases, message. Some also carry code, the stable value to handle in your code.

402 Payment Required

1{2 "error": "Payment Required",3 "message": "Limite de créditos excedido",4 "code": "CREDITS_EXHAUSTED"5}

Status	Error	When it happens	What to do
400	Invalid CPF format	The CPF does not have 11 numeric digits.	Fix the CPF before resending.
400	Invalid birthdate	birthdate is missing or not in YYYY-MM-DD format.	Send a valid date.
400	INVALID_BATCH · INVALID_QUERY	Empty batch, more than 1,000 items or malformed body; or invalid pagination parameters.	Fix the body or the query.
401	Invalid or missing API key	x-api-key header missing, key invalid or revoked, or a key from another environment (code WRONG_ENVIRONMENT).	Check the key in the dashboard.
402	CREDITS_EXHAUSTED	Free plan with no credits left in the cycle, or a batch larger than the balance.	Wait for renewal or subscribe to a plan.
403	ACCOUNT_BLOCKED	Account suspended or blocked.	Contact support.
404	CPF not found	Valid CPF with no match in the official source (or a different date of birth).	This is a normal result. Do not retry with the same data.
400	INVALID_DOCUMENT	Document validation: the body has no text `document` field.	Send the CPF or CNPJ in the document field.
400	INVALID_CNPJ_FORMAT	The CNPJ does not have 14 characters or the check digits do not match.	Fix the CNPJ. To only check a number, use `POST /v1/validate`.
404	CNPJ not found	Valid CNPJ, but no record in the open data (code CNPJ_NOT_FOUND).	This is a normal result. Do not retry with the same data.
404	BATCH_NOT_FOUND	Batch does not exist, belongs to another account or has expired (24 hours).	Send the batch again.
422	Invalid check digit	The CPF check digits do not match.	Fix the CPF.
429	Rate limit exceeded	You went over your plan’s requests-per-second limit.	Wait for the time in the `Retry-After` header.
429	Too many attempts for this CPF	Too many different birth dates were tried for this CPF (code CPF_ATTEMPTS_EXCEEDED). The lock applies to that CPF only.	Confirm the birth date with the holder and wait for `Retry-After`. No credit is charged.
429	Too many unsuccessful lookups	The account had too many lookups with no result (404) in a short time (code ACCOUNT_MISS_BUDGET_EXCEEDED).	Validate the data before looking up and wait for `Retry-After`. If this is a mistake, contact support.
429	Batch rate limit exceeded / Too many batches in progress	Batches sent too many items per minute, or too many items are waiting to be processed (codes BATCH_RATE_LIMITED and BATCH_BACKLOG).	Wait for the batches in progress to finish, then send the next one.
500 · 503	Service unavailable	Temporary failure in our infrastructure or the official source.	Retry with growing intervals.