Pular para o conteúdo principal
A API da Caratuva retorna erros com um envelope consistente: 
{
  "statusCode": 400,
  "error": "KybNotApproved",
  "message": "Your organization has no virtual account. Complete KYB first.",
  "requestId": "b1f2c3d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
}
Todo erro carrega statusCode, message e requestId. Todo código de erro documentado abaixo também carrega um error legível por máquina.
CampoPara quê
statusCodeEspelha o status HTTP.
errorCódigo estável, legível por máquina. Faça switch nele. Presente em todo código de erro documentado (alguns 404s de nível de framework o omitem).
messageExplicação legível. Uma string para a maioria dos erros; um array de strings path: reason para ValidationError. Não faça switch nele — o texto pode mudar.
requestIdUm UUID que correlaciona com nossos logs, também retornado no header de resposta x-request-id. Inclua-o em pedidos de suporte.

​
Mapeamento de status HTTP

StatusQuando
400Validação falhou, regra de negócio violada ou pré-condição não atendida.
401Credencial ausente, malformada, expirada ou revogada.
403Autenticado, mas a credencial não tem o escopo ou papel exigido.
404Recurso não existe ou não é visível à sua organização.
409Conflito — geralmente IdempotencyKeyConflict ou disputa em um campo único.
429Limite de taxa excedido.
500Erro inesperado no servidor. Seguro retentar com a mesma Idempotency-Key.
503Manutenção da plataforma ou indisponibilidade de um rail upstream. Veja status.caratuva.com. Pode ser retornado pela borda sem o envelope JSON padrão.

​
Códigos de erro comuns

A lista abaixo cobre os códigos que você provavelmente encontrará durante a integração.

​
Autenticação

CódigoStatusCausa
AuthenticationRequired401Nenhuma credencial apresentada. Envie X-API-Key (ou, para o painel, Authorization: Bearer).
InvalidApiKeyFormat401Header não está no formato pk_(test|live)_<id>.<secret>.
InvalidApiKey401Chave desconhecida, revogada ou não bate com o hash armazenado.
JwtExpired401Bearer JWT passou do exp. Reautentique pelo painel.
InvalidJwt401Bearer JWT malformado, assinatura inválida ou claims ausentes.
InsufficientScope403A chave de API não tem o escopo exigido pelo endpoint.

​
Validação

CódigoStatusCausa
ValidationError400Corpo da requisição falhou na validação de schema. message é um array de strings path: reason.
IdempotencyKeyConflict409A Idempotency-Key já foi usada para um recurso diferente. Use uma chave nova.

​
Ciclo de vida

CódigoStatusCausa
KybNotApproved400Sua organização não passou pelo KYB. Operações em produção são gateadas; o modo teste continua funcionando.
ProductionAccessNotApproved400O modo produção ainda não está habilitado. Envie uma Solicitação de Acesso à Produção e aguarde a aprovação da Caratuva.
AmountBelowMinimum400O valor em USD está abaixo do piso de funding de US$ 10,00 da transferência bancária, então o comprador não conseguiria pagá-lo. Aumente o valor.
PixPayoutKeyMissing400Nenhuma chave de repasse PIX cadastrada. Configure os Repasses no painel primeiro.
InvalidInvoiceState400Tentou editar ou reatribuir uma fatura além do seu estado editável (draft / awaiting_approval).
InvalidTransition400Transição de estado ilegal — ex.: cancelar uma fatura ou payment intent que já passou do ponto cancelável.
Um e-mail de comprador ausente ou inválido aparece como ValidationError, não como um código dedicado. Refazer um POST com o mesmo externalId retorna o intent existente em vez de um erro (veja Payment intents).

​
Limite de taxa

CódigoStatusCausa
RateLimitExceeded429Você excedeu o limite por chave de API. O corpo JSON inclui retryAfter (segundos) — espere esse tempo e retente.

​
Servidor

CódigoStatusCausa
InternalServerError500Falha inesperada no lado do servidor. Seguro retentar com a mesma chave de idempotência.

​
Guia de retentativa

StatusRetentar?Como
4xx (exceto 429)NãoA requisição falhará da mesma forma de novo. Corrija a entrada.
429SimEspere retryAfter segundos (do corpo da resposta), então retente. Não martele.
500, 502, 503, 504SimCom backoff exponencial, reusando a mesma Idempotency-Key para que uma retentativa não possa criar um recurso duplicado.
Erro de rede / timeoutSimIgual a 5xx. O original pode ou não ter comitado; reusar a chave de idempotência mantém tudo seguro.

​
O que logar

Quando uma chamada de API falha, logue:
  • requestId — permite encontrarmos sua requisição exata em nossos logs (também no header de resposta x-request-id).
  • error — o código de máquina estável.
  • O endpoint e o corpo da requisição com segredos redatados (nunca logue a metade segredo da chave de API nem headers Idempotency-Key se codificarem dados de usuário).
Uma boa abertura de suporte inclui o requestId e o código error. Com esses dois, geralmente respondemos em minutos.