> ## Documentation Index > Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt > Use this file to discover all available pages before exploring further. # Erros > Envelope de erro, códigos de status HTTP e os códigos de erro que você encontrará de fato. A API da Caratuva retorna erros com um envelope consistente: ```json theme={null} { "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)_.`. | | `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](/pt-BR/api-reference/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.