Erros

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.

Campo	Para quê
`statusCode`	Espelha o status HTTP.
`error`	Código estável, legível por máquina. Faça switch nele. Presente em todo código de erro documentado (alguns `404`s de nível de framework o omitem).
`message`	Explicaçã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.
`requestId`	Um 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

Status	Quando
`400`	Validação falhou, regra de negócio violada ou pré-condição não atendida.
`401`	Credencial ausente, malformada, expirada ou revogada.
`403`	Autenticado, mas a credencial não tem o escopo ou papel exigido.
`404`	Recurso não existe ou não é visível à sua organização.
`409`	Conflito — geralmente `IdempotencyKeyConflict` ou disputa em um campo único.
`429`	Limite de taxa excedido.
`500`	Erro inesperado no servidor. Seguro retentar com a mesma `Idempotency-Key`.
`503`	Manutençã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ódigo	Status	Causa
`AuthenticationRequired`	401	Nenhuma credencial apresentada. Envie `X-API-Key` (ou, para o painel, `Authorization: Bearer`).
`InvalidApiKeyFormat`	401	Header não está no formato `pk_(test\|live)_<id>.<secret>`.
`InvalidApiKey`	401	Chave desconhecida, revogada ou não bate com o hash armazenado.
`JwtExpired`	401	Bearer JWT passou do `exp`. Reautentique pelo painel.
`InvalidJwt`	401	Bearer JWT malformado, assinatura inválida ou claims ausentes.
`InsufficientScope`	403	A chave de API não tem o escopo exigido pelo endpoint.

Validação

Código	Status	Causa
`ValidationError`	400	Corpo da requisição falhou na validação de schema. `message` é um array de strings `path: reason`.
`IdempotencyKeyConflict`	409	A `Idempotency-Key` já foi usada para um recurso diferente. Use uma chave nova.

Ciclo de vida

Código	Status	Causa
`KybNotApproved`	400	Sua organização não passou pelo KYB. Operações em produção são gateadas; o modo teste continua funcionando.
`ProductionAccessNotApproved`	400	O modo produção ainda não está habilitado. Envie uma Solicitação de Acesso à Produção e aguarde a aprovação da Caratuva.
`AmountBelowMinimum`	400	O 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.
`PixPayoutKeyMissing`	400	Nenhuma chave de repasse PIX cadastrada. Configure os Repasses no painel primeiro.
`InvalidInvoiceState`	400	Tentou editar ou reatribuir uma fatura além do seu estado editável (`draft` / `awaiting_approval`).
`InvalidTransition`	400	Transiçã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ódigo	Status	Causa
`RateLimitExceeded`	429	Você excedeu o limite por chave de API. O corpo JSON inclui `retryAfter` (segundos) — espere esse tempo e retente.

Servidor

Código	Status	Causa
`InternalServerError`	500	Falha inesperada no lado do servidor. Seguro retentar com a mesma chave de idempotência.

Guia de retentativa

Status	Retentar?	Como
4xx (exceto 429)	Não	A requisição falhará da mesma forma de novo. Corrija a entrada.
429	Sim	Espere `retryAfter` segundos (do corpo da resposta), então retente. Não martele.
500, 502, 503, 504	Sim	Com backoff exponencial, reusando a mesma `Idempotency-Key` para que uma retentativa não possa criar um recurso duplicado.
Erro de rede / timeout	Sim	Igual 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.

Visão geral

Integração

Endpoints

Mapeamento de status HTTP

Códigos de erro comuns

Autenticação

Validação

Ciclo de vida

Limite de taxa

Servidor

Guia de retentativa

O que logar

​Mapeamento de status HTTP

​Códigos de erro comuns

​Autenticação

​Validação

​Ciclo de vida

​Limite de taxa

​Servidor

​Guia de retentativa

​O que logar

Mapeamento de status HTTP

Códigos de erro comuns

Autenticação

Validação

Ciclo de vida

Limite de taxa

Servidor

Guia de retentativa

O que logar