Erros

Toda resposta de erro (4xx/5xx) segue o RFC 7807 — mesmo shape, sempre:

{
  "type": "ERR_INTEGRATION_006",
  "title": "Método não disponível",
  "status": 422,
  "detail": "O método de pagamento informado não está habilitado no projeto.",
  "instance": "/api/v1/transactions"
}

Campo	O que é
`type` / `errorCode`	Código estável do erro — use ele no seu código, não a mensagem
`title`	Título curto legível
`status`	HTTP status (repetido no corpo)
`detail`	Explicação do que aconteceu
`instance`	Path da requisição que falhou
`details`	Extras quando existem — ex.: `issues` com os campos inválidos em erros de validação

Trate erros pelo status + type. As mensagens (title/detail) podem melhorar com o tempo; os códigos não mudam.

O que fazer com cada status

Status	Significado	O que fazer
`400`	Payload inválido (validação)	Não repita sem corrigir. Veja `details.issues` — lista campo a campo o que falhou.
`401`	API key ausente, inválida ou revogada	Confira o header `Authorization: Bearer sk_...` e se a chave não foi revogada no Dashboard.
`403`	Autenticado, mas sem permissão	Cheque o tipo de chave e o modo do projeto (projeto em sandbox bloqueia `sk_live_`).
`404`	Recurso não encontrado	ID errado ou de outro projeto — a API não revela recursos de terceiros.
`409`	`Idempotency-Key` em processamento	Outra requisição com a mesma chave está em voo. Aguarde ~1s e repita com a mesma chave — você recebe o replay. Veja Idempotência.
`422`	Erro semântico	O payload é válido, mas algo do negócio impede: método não disponível, valor acima do limite do projeto, chave idempotente reusada com body diferente. Corrija a causa antes de repetir.
`429`	Rate limit	Aguarde o header `Retry-After` (segundos) antes de repetir. Backoff exponencial se persistir.
`500`	Erro interno	Repita com backoff. Se persistir, fale com o suporte informando o `instance` e o horário.
`503`	Processamento temporariamente indisponível ou sistema sob carga	Transitório — repita com backoff. Na criação de transação, use Idempotency-Key para repetir sem risco de duplicar.

Códigos que você vai encontrar

`type`	Status	Quando acontece
`ERR_VALIDATION_001`	400	Campos inválidos no body/query (detalhes em `details.issues`)
`ERR_AUTH_009`	401	API key inválida ou expirada
`ERR_AUTHZ_001`	403	Chave sem a permissão necessária para o recurso
`ERR_TRANSACTION_001`	404	Transação não encontrada
`ERR_INTEGRATION_006`	422	Método de pagamento não disponível no projeto

Caso especial: HTTP 202 na criação

202 não é erro — é sucesso parcial. O PIX foi gerado, mas a persistência ficou pendente de reconciliação automática:

data.id vem null; use data.externalId como referência
O pixCode é válido e pagável — entregue ao comprador normalmente
A transação aparece na listagem em alguns minutos, após a reconciliação

Timeouts

A criação de transação pode levar até 30 segundos no pior caso. Configure o timeout do seu cliente HTTP acima disso (o SDK usa 35s) e, ao repetir após timeout, use a mesma Idempotency-Key — se a criação tiver concluído, você recebe o replay em vez de um pagamento duplicado.

Primeiros passos

Conceitos principais

Formas de integração

Webhooks

Usando a Bob

Fundamentos da API

O que fazer com cada status

Códigos que você vai encontrar

Caso especial: HTTP 202 na criação

Timeouts

Próximos passos

Idempotência

Configurar webhooks

​O que fazer com cada status

​Códigos que você vai encontrar

​Caso especial: HTTP 202 na criação

​Timeouts

​Próximos passos

Idempotência

Configurar webhooks

O que fazer com cada status

Códigos que você vai encontrar

Caso especial: HTTP 202 na criação

Timeouts

Próximos passos