Errors

Every error of the /v2/ routes responds with an RFC 7807 body (application/problem+json). POST /oauth/token responds in the format { "error", "error_description" }; see Authentication. title is a contract and does not change; detail is text for people; type is a URL ending in /erros/ followed by the title: compare by the title, never by the domain of the URL. violacoes carries, when present, the field and the number that was missing.

PUT /v2/ex/pix/SAQ03J1ZK7M9QW3ERT5TY6UI8O
{
  "tipo": "SAQUE",
  "valor": "10000.00",
  "solicitadoEm": "2026-09-18T12:00:00Z",
  "favorecido": { "chave": "12345678909", "cpf": "12345678909" }
}
→ 422
{
  "type": ".../erros/saldo_insuficiente",
  "title": "saldo_insuficiente",
  "status": 422,
  "detail": "saldo disponível insuficiente",
  "correlationId": "01M2SX29RA7F19V4Q76VFTSAHS",
  "violacoes": []
}

Handle errors by the title, not by the status. A 4xx does not change by repeating the same request right away. A 429 clears after the Retry-After; the ones that depend on state, such as saldo_insuficiente, limite_excedido, dia_nao_encerrado and reenvio_em_andamento, clear when the state changes. A 5xx or a timeout does not mean the operation failed: look up the resource by its id before creating another one.

Catalog #

Status	`title`	When
400	`json_invalido`	The body is not JSON.
400	`requisicao_invalida`	A required field is missing or the body is malformed.
400	`campo_desconhecido`	A field the route does not know, where the route rejects that.
400	`valor_invalido`	Money outside the format `"0.00"` or outside the range: zero on a charge, payout or refund, or above the maximum.
400	`tipo_invalido`	Payout `tipo` other than `SAQUE` or `PREMIO`.
400	`natureza_invalida`	Refund `natureza` outside the list.
400	`txid_invalido`	`txid` outside 26 to 35 alphanumeric characters.
400	`id_envio_invalido`	`idEnvio` outside the format.
400	`id_invalido`	Refund or sub-account id outside the format.
400	`cpf_invalido`	CPF outside the format.
400	`cnpj_invalido`	CNPJ outside the format: 14 positions without punctuation, the first 12 digits or letters (a lowercase letter is read as uppercase) and the last 2 digits, with the check digits.
400	`filtro_invalido`	Invalid listing filter, such as `cpf` and `cnpj` together.
400	`documento_invalido`	The document of the payee is not a valid CPF or CNPJ, or is missing; or the charge carries `devedor.cpf` and `devedor.cnpj` together.
400	`devedor_obrigatorio`	Charge without `devedor.cpf` or `devedor.cnpj`.
400	`devedor_pj_nao_permitido`	Charge with `devedor.cnpj` where `capacidades.devedorPJ` is `false`.
400	`chave_nao_pertence_ao_documento`	The owner of the key is not the informed CPF or CNPJ.
400	`favorecido_pj_nao_permitido`	A payee that is a legal entity, or a key of a legal entity with `favorecido.cpf`, where `capacidades.favorecidoPJ` is `false`.
400	`chave_pix_invalida`	The key does not have the shape of any key type, or it is a CPF or CNPJ with invalid check digits.
400	`solicitado_em_invalido`	`solicitadoEm` outside the format or more than 5 minutes in the future.
400	`validade_invalida`	Payout `validadeSegundos` outside 60 to 10800.
400	`periodo_invalido`	`de`, `ate`, `inicio` or `fim` outside the format.
400	`periodo_obrigatorio`	Summary without `de` or without `ate`.
400	`data_invalida`	Date outside `AAAA-MM-DD`.
400	`cursor_invalido`	Malformed cursor.
400	`limite_invalido`	`limite` outside 1 to 200.
400	`status_invalido`	Status filter outside the list.
400	`url_invalida`	Invalid webhook URL or a URL without HTTPS.
400	`url_privada`	Webhook URL on a private network, or a host that does not resolve in DNS.
400	`familia_desconhecida`	Webhook redirect for a family that does not exist.
400	`tipos_invalidos`	`tiposHabilitados` with a blank item.
400	`janela_invalida`	Resend with `fim` equal to or before `inicio`, or `inicio` in the future.
400	`janela_muito_antiga`	Resend with `inicio` more than 30 days ago.
401	`acesso_negado`	Call without `Authorization: Bearer`.
401	`token_invalido`	Invalid or expired token. Renew it.
401	`token_revogado`	Token revoked before it expired. Request another token once; if the request is refused, talk to support.
403	`origem_nao_permitida`	The source IP is not among the IPs registered on the credential.
403	`escopo_insuficiente`	The token does not have the scope of the route.
403	`merchant_nao_provisionado`	The `client_id` does not have an account.
403	`conta_bloqueada`	The account is not `ATIVA`.
403	`conta_em_abertura`	The account cannot charge or pay out yet: the institution is defining where it operates. Reads and webhooks work.
403	`conta_cnpj_nao_ativo`	The account's CNPJ is not ATIVA (active) at the Brazilian Federal Revenue: new charges and payouts stay blocked until it is active again. Reads and webhooks work.
403	`subconta_indisponivel`	The sub-account is not `ATIVA`.
403	`subconta_de_outro`	A sub-account credential asking for another sub-account.
404	`nao_encontrado`	The resource does not exist in this account.
409	`txid_duplicado`	`txid` reused with a different debtor, amount, `ex.subconta` or `ex.splitConfig`.
409	`id_envio_duplicado`	`idEnvio` reused with a different amount, `tipo`, payee document, `subconta` or `exigirAprovacao`.
409	`id_duplicado`	Id reused with a different body.
409	`reenvio_em_andamento`	There is already a webhook resend in progress.
413	`corpo_grande_demais`	Body larger than 1 MiB.
422	`saldo_insuficiente`	The available balance does not cover the amount. On a payout, the amount plus the fee.
422	`saldo_bloqueado_med`	The available balance does not cover the payout and the account has balance on hold. `GET /v2/ex/bloqueios` lists each hold.
422	`limite_excedido`	Above a limit. The numbers are in `violacoes`.
422	`favorecido_restrito`	The CPF of the payee is restricted.
422	`chave_sob_reivindicacao`	The key is under portability or a claim.
422	`chave_exige_documento`	On this account a payout only goes to the key that is the valid CPF or CNPJ of the payee, and the key sent is an email, phone, random key or a document with invalid check digits. See `capacidades.saqueQualquerChave` in `GET /v2/ex/config`.
422	`documento_exigido_pela_nominal`	The payout came without the payee document, with the document optional on your account, and the account it goes out through requires the document. Send `favorecido.cpf` or `favorecido.cnpj`.
422	`valor_abaixo_do_minimo`	The payout amount is below the minimum payout of the account, or the charge amount is below the minimum charge. The minimum comes in `detail`, and nothing is created.
422	`valor_acima_do_maximo`	The payout amount is above the maximum per payout Pix of the account, or the charge amount is above the maximum charge. The maximum comes in `detail`, and nothing is created.
422	`pagamento_negado_compliance`	Rejected by the risk analysis. Do not repeat.
422	`cadeia_retry_invalida`	Invalid `idEnvioOriginal` for repeating the payout.
422	`cobranca_recusada_no_custodiante`	The institution of the account refused to issue the QR. The charge was not created; do not repeat with the same body.
422	`nome_do_pagador_obrigatorio`	On this account a charge requires `devedor.nome`, with the first name and the surname where the CPF of the payer arrives masked. See `capacidades.cobrancaSemNome` in `GET /v2/ex/config`.
422	`titularidade_sem_confirmacao`	On this account a charge with the payer document is not accepted. Contact support.
422	`pix_nao_creditado`	Refund of a Pix that was not credited or is on hold.
422	`devolucao_unica`	On this account each Pix accepts a single refund, and this one already has one.
422	`devolucao_so_integral`	On this account a refund can only be for the whole amount of the Pix, and the requested `valor` is lower.
422	`devolucao_de_outra_conta`	The Pix came in before the balance of your account was transferred to another institution. Its refund is made by us: talk to support.
422	`devolucao_excede_recebido`	The sum of the refunds would exceed the amount received.
422	`devolucao_prazo_excedido`	90 days have passed since settlement.
422	`subconta_nao_encontrada`	The informed sub-account does not exist.
422	`split_config_nao_encontrada`	`ex.splitConfig` does not exist.
422	`dia_nao_encerrado`	Statement or closing balance of the current day.
422	`periodo_nao_encerrado`	Summary of a period that is still open.
422	`periodo_longo_demais`	Summary longer than 366 days.
422	`saque_nao_liquidado`	Receipt of a payout that is not `REALIZADO`.
422	`webhook_nao_configurado`	Test without an active webhook.
429	`limite_requisicoes`	Above the request limit. Respect `Retry-After`.
500	`erro_interno`	An error on our side.
502	`custodiante_indisponivel`	Failure to issue the QR at the custodian institution. The charge was not created; repeat with the same `txid`. If it responds `502` again without the `Retry-After` header, create it with a new `txid`. With `Retry-After`, repeat with the same `txid` after the indicated time, in seconds: `1` when the institution was slow and the issuance continues (the QR that arrives is saved, and the retry receives the charge), when the same charge is being issued in another request, or when the institution has too many charges waiting or yours already take half of its slots; the time left in the pause when the institution stopped issuing the QR for your charges and their issuance is paused; and the time the institution asked for when it limited the requests.
503	`dict_resolucao_incompleta`	The directory did not return the account of the payee. Repeat.
503	`capacidade_indisponivel`	The account does not have the capability the route requires. `GET /v2/ex/config` lists the capabilities of the account and the origin of each one.

Request limits #

The API does not limit requests per second: there is no cap on charges, withdrawals, reads or the event feed.

An account that loops because of a defect may receive a limit from the institution. Only in that case do responses carry x-ratelimit-remaining, and a 429 carries Retry-After.