> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Catálogo de códigos de erro

> As mensagens de erro da API da Finvia, agrupadas por rota, com a causa e a ação recomendada.

Este catálogo reúne as respostas de erro de cada rota da API. As mensagens estão **exatamente** como a API as devolve: algumas em português, outras em inglês, às vezes na mesma rota. Use a página para montar o tratamento de erros, configurar alertas e orientar o suporte.

Para o formato geral das respostas e a regra de quando repetir uma requisição, veja [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md).

## Como ler as tabelas

| Coluna | Conteúdo |
| - | - |
| **HTTP** | Código de status da resposta |
| **Mensagem ou código** | Valor literal de `message` ou, nas rotas que usam código de negócio, o valor de `code` (Apple Pay e validação de cartão) ou de `error` (envio de documentos com token). `X` e `Y` indicam valores que variam |
| **Causa** | O que provoca o erro |
| **Ação** | O que fazer |

A API usa três formatos de corpo:

| Formato | Onde |
| - | - |
| `{ "statusCode", "message", "error" }` | Padrão. Em erros de validação do corpo (`400`), `message` vem como lista, um item por problema |
| `{ "code", "message" }` | Erros de negócio do Apple Pay e validação de cartão em `POST /v1/subscriptions` |
| `{ "error", "message", "details" }` | Erros de arquivo em `POST /v1/document-uploads` |

> [!TIP]
>
> **Para o desenvolvedor:** decida o fluxo pelo código HTTP e, quando existir, pelo `code` ou pelo `error` dos dois últimos formatos. Use o texto de `message` só para log e diagnóstico: ele mistura idiomas e pode mudar.

## Erros comuns a todas as rotas

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `400` | Lista em `message`, com `error` `Bad Request` (ex.: `["amount must not be less than 1"]`) | Campo obrigatório ausente, tipo errado ou valor fora do limite | Corrija cada item da lista e envie de novo |
| `401` | `Unauthorized` | Chave inválida, cabeçalho `Authorization` ausente ou formato incorreto. O corpo é `{ "statusCode": 401, "message": "Unauthorized" }` | Confira a chave, o prefixo `Basic ` e se o Base64 decodificado termina em `:` |
| `403` | `Acesso negado` | O perfil do usuário que gerou a chave não tem permissão para a rota. O corpo é `{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }` | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#permissões-da-chave) |
| `500` | `Internal server error` | Erro interno | Em consultas, tente de novo com espera crescente. Em criações, verifique se o recurso foi criado antes de repetir |

## Cobranças

### `POST /v1/charges`

| HTTP | Mensagem ou código | Causa | Ação |
| - | - | - | - |
| `400` | `Shipping info must be provided for merchants selling physical items.` | Algum item é `physical` e o corpo não traz `shippingAddress`. Nenhuma cobrança é criada | Envie `shippingAddress` com `postalCode`, `addressLine1`, `city`, `state` e `country` |
| `400` | Lista em `message`, ex.: `["shippingAddress.country must be a valid ISO31661 Alpha3 code"]` | `shippingAddress` incompleto ou inválido, ou outro campo fora do contrato | Corrija os campos indicados. País em 3 letras (`BRA`) |
| `400` | `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem `cvv` | Colete o CVV do comprador e envie junto com o `cardTokenId` |
| `400` | Erro de validação do cartão salvo | O cartão do `cardTokenId` está revogado, expirado ou pendente de ativação | Use outro cartão. Confira o status em `GET /v1/cards` |
| `403` | `Acesso negado` | Chave de usuário Desenvolvedor | Gere a chave com usuário Owner ou Manager |
| `422` | `Fees not configured` | A conta não tem taxa configurada para o método, a moeda ou o número de parcelas. Vale também no Modo Teste | Fale com o suporte da Finvia |
| `500` | `Internal server error` | Erro interno | Siga o [procedimento de timeout](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#procedimento-depois-de-um-timeout-ao-criar-cobrança) antes de repetir |

Recusas chegam com `201`, `status` `refused` ou `failed` e o motivo em `reason`. Também sai o webhook `charge.refused` ou `charge.failed`.

| `reason` (literal) | Causa | Ação |
| - | - | - |
| `card_declined` | Recusa do cartão de teste `4444333322221112` no Modo Teste. Em produção, o `reason` traz o motivo informado pelo processador | Oferecer outro cartão ou Pix |
| `3ds_required: Não foi possível completar a autenticação 3DS obrigatória` | A conta exige 3D Secure e a cobrança veio sem autenticação, ou o 3DS não pôde ser feito | Fazer a autenticação 3DS antes de criar a cobrança |
| `3ds_failed: The cardholder failed to authenticate. Please try again or use a different card` | O comprador não passou na autenticação | Pedir nova tentativa ou outro cartão |
| `3ds_incomplete: Required authentication data (cryptogram or ECI) is missing` | 3DS obrigatório e `cryptogram` ou `eci` ausentes ou `null` | Repassar o resultado completo de `challenge-result`, sem enviar campos `null` |
| `3ds_<estado>: Authentication did not succeed` | No 3DS gerenciado, a autenticação não passou (`<estado>` é o estado final) | Pedir nova tentativa ou outro cartão |
| `antifraud_denied` | Recusa pela análise antifraude da conta | Oferecer outra forma de pagamento |

Quando a análise antifraude manda a cobrança para revisão manual, ela fica `in_analysis` com `reason` `antifraud_manual_review`. Não é recusa: aguarde o desfecho.

Erros de Apple Pay nesta rota, no formato `{ code, message }`:

| HTTP | Código | Causa | Ação |
| - | - | - | - |
| `400` | `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | `customer.document` ausente. O token da Apple não traz CPF ou CNPJ | Coletar o documento no checkout antes de abrir o Apple Pay |
| `422` | `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | Moeda diferente de `BRL` | Usar `BRL` |
| `400` | `APPLE_PAY_TOKEN_INVALID` | O objeto em `wallet.token` não está no formato do token da Apple | Enviar o `payment.token` na íntegra, sem reescrever campos |
| `400` | `APPLE_PAY_PROVIDER_REJECTED` | O processador recusou a operação ou devolveu resposta fora do contrato | Verificar o token e tentar de novo. Persistindo, falar com o suporte |
| `422` | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | O processador de Apple Pay não está configurado para a conta | Falar com o suporte |
| `503` | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Processador indisponível | Tentar de novo mais tarde |
| `500` | `APPLE_PAY_PROVIDER_AUTH_FAILED` | Falha de autenticação entre a Finvia e o processador | Falar com o suporte |

### `GET /v1/charges` e `GET /v1/charges/{id}`

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `401` | `Unauthorized` | Credencial inválida | Ver erros comuns |
| `403` | `Acesso negado` | Perfil sem permissão | Ver erros comuns |

> [!WARNING]
>
> `GET /v1/charges/{id}` com um `id` que não existe responde hoje `200` com corpo vazio, sem `404`. Trate corpo vazio como "cobrança não encontrada". Confira também se a chave é do mesmo ambiente da cobrança: a chave de teste só enxerga cobranças de teste.

### `POST /v1/refunds`

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `404` | `Cobrança não encontrada` | `chargeId` inexistente, ou cobrança que não está `paid` (já estornada, pendente, `pre_chargeback` ou `chargeback`) | Consultar a cobrança antes de pedir o estorno |
| `422` | `Já existe um reembolso para esta cobrança` | Segundo pedido de estorno para a mesma cobrança | Não repetir. Cada cobrança aceita um único estorno |
| `501` | `Reembolso não implementado para este método de pagamento` | O método da cobrança não tem estorno pela API | Falar com o suporte |
| `501` | `Reembolso não disponível para este provedor de pagamento` | O provedor da cobrança não oferece estorno | Falar com o suporte |
| `500` | `Internal server error` | Erro interno | Consultar a cobrança antes de repetir |

### `POST /v1/charges/{id}/resend-webhook`

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `400` | Lista em `message` | `status` fora da lista aceita (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`). `pre_chargeback` e `chargeback` não são aceitos | Usar um dos status aceitos |
| `403` | `Redisparo de webhook disponível apenas para cobranças de teste` | A cobrança foi criada com chave de produção | Usar uma cobrança criada com chave `sk_test_` |
| `403` | `Acesso negado` | Perfil sem permissão | Ver erros comuns |
| `404` | `Cobrança não encontrada` | `id` inexistente | Conferir o `id` |

## Apple Pay (domínios e sessão)

Erros de negócio no formato `{ code, message }`. Erros de validação de campo vêm no formato padrão, com `message` em lista, e o `403` de permissão traz `Acesso negado`.

| Rota | HTTP | Código | Causa | Ação |
| - | - | - | - | - |
| `POST /v1/apple-pay/domains` | `400` | `APPLE_PAY_INVALID_DOMAIN` | `domain` não é um hostname puro (tem esquema, porta, caminho, é um IP ou passa de 255 caracteres) | Enviar só o hostname, como `checkout.minhaloja.com.br` |
| `POST /v1/apple-pay/domains` | `409` | `APPLE_PAY_DOMAIN_ALREADY_REGISTERED` | Dois registros simultâneos do mesmo hostname | Repetir a chamada: a rota devolve o registro existente |
| `POST /v1/apple-pay/domains` | `400` | `APPLE_PAY_PROVIDER_REJECTED` | O provedor recusou o registro | Verificar o hostname e tentar de novo |
| `POST /v1/apple-pay/domains` | `403` | `Acesso negado` | O usuário dono da chave não tem a permissão de domínios Apple Pay (Owner, Manager e Desenvolvedor têm) | Usar a chave de um desses perfis |
| `POST /v1/apple-pay/domains/{id}/validate` | `404` | `APPLE_PAY_DOMAIN_NOT_FOUND` | Domínio inexistente ou de outra conta | Conferir o `id` com `GET /v1/apple-pay/domains` |
| `POST /v1/apple-pay/domains/{id}/validate` | `422` | `APPLE_PAY_DOMAIN_VERIFICATION_FAILED` | Arquivo de verificação ausente ou inacessível. O domínio vai para `failed`, `verifiedAt` volta a `null` e o motivo fica em `lastVerificationError` | Corrigir a hospedagem do arquivo e validar de novo |
| `GET /v1/apple-pay/domains/{id}` | `404` | `APPLE_PAY_DOMAIN_NOT_FOUND` | Domínio inexistente ou de outra conta | Conferir o `id` |
| `POST /v1/apple-pay/validate-merchant` | `400` | `APPLE_PAY_INVALID_VALIDATION_URL` | `validationUrl` não é HTTPS em host `apple.com` (ou subdomínio), tem porta ou passa de 2048 caracteres | Enviar o `event.validationURL` recebido da Apple sem alterar |
| `POST /v1/apple-pay/validate-merchant` | `400` | `APPLE_PAY_INVALID_DOMAIN` | `domain` inválido | Enviar o `window.location.hostname` |
| `POST /v1/apple-pay/validate-merchant` | `400` | `APPLE_PAY_DOMAIN_NOT_VERIFIED` | O domínio não é da conta da `pk_`, não foi registrado ou ainda não foi verificado | Registrar e verificar o hostname exato da página |
| `POST /v1/apple-pay/validate-merchant` | `422` | `APPLE_PAY_PROVIDER_NOT_ENABLED` | A conta ainda não registrou nenhum domínio | Registrar o primeiro domínio |
| `POST /v1/apple-pay/validate-merchant` | `429` | `APPLE_PAY_RATE_LIMITED` | Mais de 20 tentativas por IP a cada 5 minutos, ou teto global da plataforma | Aguardar e validar uma vez por clique |
| Todas as rotas de Apple Pay | `422` | `APPLE_PAY_PROCESSOR_NOT_CONFIGURED` | Processador de Apple Pay não configurado para a conta | Falar com o suporte |
| Todas as rotas de Apple Pay | `503` | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Provedor indisponível | Tentar de novo mais tarde |
| Todas as rotas de Apple Pay | `500` | `APPLE_PAY_PROVIDER_AUTH_FAILED` | Falha de autenticação entre a Finvia e o provedor | Falar com o suporte |

## Saldos e meios de pagamento

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `GET /v1/wallets` | `403` | `Acesso negado` | Chave de usuário Desenvolvedor | Gerar a chave com usuário Owner ou Manager |
| `GET /v1/wallets` | `404` | `Merchant not found` (corpo `{ "statusCode": 404, "message": "Merchant not found", "error": "Not Found" }`) | `merchantId` inexistente ou sem acesso | Conferir o `merchantId` |
| `GET /v1/payment-methods` | `401` | `Unauthorized` | Credencial inválida | Ver erros comuns |

## Saques

Não existe saque no Modo Teste. Os erros de regra vêm em inglês.

### `POST /v1/payout-requests` (própria conta)

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `400` | Lista em `message` | Corpo inválido (campo ausente, tipo errado) | Corrigir o corpo. Não é `422` |
| `400` | Lista em `message` | `currency` com código ISO inválido | Enviar `BRL` |
| `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Pedido com a chave de teste | Saques só em produção |
| `403` | `Acesso negado` | Chave de perfil sem permissão de saque (ex.: Desenvolvedor) | Gerar a chave com usuário Owner ou Manager |
| `404` | `Merchant not found` | `merchantId` inexistente | Enviar o id da própria conta |
| `422` | `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que `amount` | Consultar o saldo antes de sacar |
| `422` | `Maximum withdrawal amount is X` | Valor acima do limite máximo por saque configurado para a conta | Dividir o saque ou falar com o suporte |
| `422` | `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` na mesma moeda | Aguardar a decisão do saque pendente |
| `422` | `Withdrawals are disabled for this merchant` | Saques desabilitados na conta | Falar com o suporte |
| `422` | `Saques estão desabilitados para esta conta (saldo retido por configuração administrativa)` | Conta com saldo retido | Falar com o suporte |
| `422` | `Merchant account is not active` | Conta não está ativa | Falar com o suporte |
| `422` | `Merchant settings are not configured correctly` | Configuração da conta incompleta | Falar com o suporte |
| `422` | `Payout fees not configured` | Taxa de saque não configurada | Falar com o suporte |
| `422` | `Currency X is not supported for withdrawals` | Moeda válida, mas sem saque | Enviar `BRL` |
| `422` | `You can only create withdrawal requests for your own account` | `merchantId` de outra conta | Enviar o id da própria conta |
| `422` | `Payout execution failed: ...` | Falha na execução, só em contas com aprovação automática | Consultar `GET /v1/payout-requests` antes de repetir: o pedido pode ter ficado `pending` |

### `POST /v1/submerchants/{merchantId}/payout-requests` (subconta)

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `400` | Lista em `message`, ex.: `["amount must be a positive number", "amount must not be less than 1"]` | `amount` ausente, zero ou abaixo de `1` | Enviar o valor em reais, mínimo `1` |
| `403` | `Fast Connect not enabled.` | Connect não habilitado na conta master | Pedir a habilitação |
| `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Pedido com a chave de teste | Saques só em produção |
| `404` | `SubMerchant not found` | Subconta inexistente ou de outra conta master | Conferir o `merchantId` |
| `422` | `SubMerchant account is not active` | Subconta não está `active` | Aguardar a aprovação da subconta |
| `422` | `SubMerchant is blocked. Withdrawals are not allowed.` | Subconta bloqueada | Falar com o suporte |
| `422` | `SubMerchant CNPJ not configured` | Subconta sem CNPJ cadastrado (o CNPJ é a chave Pix do saque) | Completar o cadastro da subconta |
| `422` | `Withdrawals are disabled for this submerchant` | Saques desabilitados na subconta | Falar com o suporte |
| `422` | `Insufficient balance. Required: X, Available: Y` | Saldo disponível insuficiente | Consultar o saldo antes de sacar |
| `422` | `Maximum withdrawal amount is X BRL` | Valor acima do limite por saque | Dividir o saque |
| `422` | `You already have a pending withdrawal request for this currency` | Já existe saque `pending` | Aguardar a decisão |
| `422` | `Merchant settings are not configured correctly` | Configuração incompleta | Falar com o suporte |
| `422` | `Payout fees not configured` | Taxa de saque não configurada | Falar com o suporte |

### `GET /v1/payout-requests`

| HTTP | Mensagem | Causa | Ação |
| - | - | - | - |
| `403` | `Acesso negado` | Chave de usuário Desenvolvedor | Gerar a chave com usuário Owner ou Manager |
| `404` | `Merchant not found` | `merchantId` de uma conta sem acesso | Conferir o `merchantId` |
| `500` | `Internal server error` | `orderBy` enviado na consulta | Não envie `orderBy`: a ordem já é do mais recente para o mais antigo |

## Clientes

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `GET /v1/customers/{id}` | `404` | `Customer not found` | `id` inexistente ou de outra conta | Conferir o `id` |
| `PUT /v1/customers/{id}` | `404` | `Customer not found` | `id` inexistente | Conferir o `id` |
| `DELETE /v1/customers/{id}` | `404` | `Customer not found` | `id` inexistente ou já removido | Conferir o `id` |

## Cartões

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `POST /v1/cards` | `400` | `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 dígitos (CPF) nem 14 (CNPJ) | Usar um cliente com e-mail e CPF ou CNPJ |
| `POST /v1/cards` | `400` | `Failed to register card` | Dados do cartão inválidos ou outra falha no registro | Conferir os dados do cartão |
| `GET /v1/cards/{id}` | `404` | `Card not found` | `id` inexistente | Conferir o `id` |
| `DELETE /v1/cards/{id}` | `404` | `Card not found` | `id` inexistente | Conferir o `id` |

## 3D Secure

As rotas abaixo usam a **chave pública** (`pk_`).

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `/v1/three-ds/*` | `401` | `Unauthorized` | Chave pública inválida | Usar a `pk_` da conta (ou `pk_test_` no sandbox) |
| `/v1/three-ds/*` | `404` | `No 3DS provider configured for this gateway` | Não há provedor 3DS configurado | Falar com o suporte para habilitar o 3DS |
| `POST /v1/three-ds/challenge-result` | `500` | Mensagem iniciada por `Authentication challenge not yet completed` | Chamada antes do fim do desafio | Chamar só depois do sinal de fim do desafio ou de um status final |
| `POST /v1/charges/{id}/resume-3ds` | `400` | `Cobrança não está utilizando 3DS gerenciado` | A cobrança não usa o 3DS gerenciado | Não chamar esta rota fora do fluxo gerenciado |
| `POST /v1/charges/{id}/resume-3ds` | `400` | Lista em `message` | `threeDS` ausente, `null` ou com `type` ou `state` `null` | Enviar o objeto `threeDS` completo |
| `POST /v1/charges/{id}/resume-3ds` | `404` | `Cobrança não encontrada ou não está aguardando autenticação` | A cobrança não está em `authentication_required` ou é de outra conta | Consultar a cobrança antes de retomar |
| `POST /v1/charges/{id}/resume-3ds` | `422` | `Dados do cartão não encontrados. Crie uma nova cobrança.` | Os dados do cartão não estão mais disponíveis | Criar uma nova cobrança |
| `POST /v1/charges/{id}/resume-3ds` | `422` | `Dados do cartão expiraram. Crie uma nova cobrança.` | Passaram os 15 minutos de guarda dos dados do cartão | Criar uma nova cobrança |
| `POST /v1/charges/{id}/resume-3ds` | `422` | `Dados de autenticação expiraram. Crie uma nova cobrança.` | A autenticação terminou depois do prazo | Criar uma nova cobrança. A anterior não é processada |

## Planos de assinatura

Todas as rotas de planos respondem `403` com `Acesso negado` para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (`GET`).

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `POST /v1/subscription-plans` | `400` | `Invalid payment methods: ...` | Método desconhecido em `paymentMethods` | Usar só os métodos aceitos |
| `POST /v1/subscription-plans` | `404` | `Merchant not found` | O `merchantId` do corpo não é de uma conta a que a chave tem acesso | Conferir o `merchantId` |
| `POST /v1/subscription-plans` | `404` | `Currency not found` | Moeda inexistente | Usar `BRL` |
| `GET /v1/subscription-plans/{id}` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` |
| `PUT /v1/subscription-plans/{id}` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` |
| `POST /v1/subscription-plans/{id}/image` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` |
| `PATCH /v1/subscription-plans/{id}/status` | `404` | `Subscription plan not found` | `id` inexistente | Conferir o `id` |
| `PATCH /v1/subscription-plans/{id}/status/confirm` | `400` | `Invalid or expired confirmation token` | Token errado, vencido (vale 5 minutos) ou substituído por um pedido de desativação mais novo | Pedir a desativação de novo e confirmar dentro do prazo |
| `PATCH /v1/subscription-plans/{id}/status/confirm` | `404` | `Subscription plan not found` | Plano inexistente ou de outra conta | Conferir o `id` |

## Assinaturas

Todas as rotas de assinaturas respondem `403` com `Acesso negado` para chaves de Desenvolvedor e Financeiro. O Visualizador só acessa as consultas (`GET`).

| Rota | HTTP | Mensagem ou código | Causa | Ação |
| - | - | - | - | - |
| `POST /v1/subscriptions` | `400` | `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | O cartão vai em `paymentMethod` e o cliente não tem e-mail ou CPF/CNPJ. Vale o documento do cliente já cadastrado com o mesmo e-mail | Usar um cliente com e-mail e CPF ou CNPJ |
| `POST /v1/subscriptions` | `400` | `Failed to create subscription` | Dados inválidos ou falha na criação | Conferir o corpo, o cartão e o cliente |
| `POST /v1/subscriptions` | `404` | `Subscription plan not found or inactive` | Plano inexistente ou com status `inactive` | Conferir o `subscriptionPlanId` e o status do plano |
| `POST /v1/subscriptions` | `422` | `CARD_VALIDATION_FAILED`, com `message` `Não foi possível validar o cartão: <motivo>` | Plano com trial grátis: a validação de R\$ 1,00 foi recusada, ficou em análise ou não teve resposta. Nada é criado | Pedir outro cartão. A `message` pode ser exibida ao comprador |
| `POST /v1/subscriptions` | `409` | `CARD_VALIDATION_IN_PROGRESS` | Já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo) | Aguardar a primeira terminar |
| `POST /v1/subscriptions` | `429` | `CARD_VALIDATION_RATE_LIMITED` | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora | Aguardar e pedir outro cartão |
| `GET /v1/subscriptions/{id}` | `404` | `Subscription not found` | `id` inexistente | Conferir o `id` |
| `PATCH /v1/subscriptions/{id}` | `400` | `Only active subscriptions can be updated` | A assinatura não está `active` (inclusive `pending_activation`) | Atualizar só assinaturas ativas |
| `PATCH /v1/subscriptions/{id}` | `404` | `Subscription not found` | `id` inexistente | Conferir o `id` |
| `POST /v1/subscriptions/{id}/cancel` | `400` | `Subscription already cancelled or expired` | A assinatura já está `cancelled` ou `expired` | Não repetir o cancelamento |
| `POST /v1/subscriptions/{id}/cancel` | `404` | `Subscription not found` | `id` inexistente | Conferir o `id` |

## Connect

As rotas do Connect respondem `403` com `Fast Connect not enabled.` quando o módulo não está habilitado na conta master.

### Subcontas

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `POST /v1/submerchants` | `400` | Lista em `message`, ex.: `["bankAccount.bankCode should not be empty"]` ou `["address.country must be a valid ISO31661 Alpha3 code"]` | Campo obrigatório ausente ou inválido. Com país `BRA`, CNPJ, UF, CEP e bairro também são validados | Corrigir os campos indicados. País em 3 letras (`BRA`) |
| `POST /v1/submerchants` | `400` | `Email already registered` | `canAccessDashboard` é `true` e o e-mail do usuário do painel já existe | Usar outro e-mail para o usuário |
| `POST /v1/submerchants` | `409` | `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.` | O CNPJ já existe entre as subcontas da mesma master (em qualquer status) ou é o CNPJ da própria master | Consultar a subconta existente com `GET /v1/submerchants?search=` |
| `POST /v1/submerchants` | `500` | `Internal server error` | Erro interno | Listar as subcontas antes de repetir |
| `GET /v1/submerchants` | `400` | Lista em `message` | Valor de `status` fora dos 7 aceitos | Usar `active`, `inactive`, `pending`, `pre_approved`, `correcting`, `rejected` ou `blocked` |
| `GET /v1/submerchants` | `500` | `Internal server error` | `orderBy` com nomes em camelCase (ex.: `legalName,-createdAt`) | Usar snake\_case: `legal_name,-created_at` |
| `GET /v1/submerchants/{id}/api-keys` | `404` | `API keys not found for this submerchant.` | A API não encontrou chaves para a subconta | Conferir o `id` e o status da subconta |

### Documentos e representantes

| Rota | HTTP | Mensagem ou código | Causa | Ação |
| - | - | - | - | - |
| `POST /v1/submerchants/{id}/document` | `400` | `Validation failed (current file type is text/plain, expected type is ...)` | Tipo de arquivo não aceito | Enviar PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) |
| `POST /v1/submerchants/{id}/document` | `400` | `File is required` | Nenhum arquivo enviado | Enviar o arquivo em `multipart/form-data` |
| `POST /v1/submerchants/{id}/document` | `400` | Mensagem padrão de validação | Arquivo acima de 50 MB | Reduzir o arquivo |
| `POST /v1/submerchants/{id}/document` | `400` | `Invalid document name` | Nome de campo fora da lista de documentos | Usar um dos seis nomes aceitos: `social_contract`, `cnpj_card`, `responsible_document_front`, `responsible_document_back`, `selfie_with_document` ou `irs_letter` |
| `POST /v1/submerchants/{id}/document` | `400` | `Bad Request` | A subconta não pertence à conta master | Conferir o `id` |
| `POST /v1/submerchants/{id}/document` | `422` | `Unprocessable Entity` (corpo `{ "statusCode": 422, "message": "Unprocessable Entity" }`) | Subconta já aprovada: os documentos não podem mais ser alterados | Falar com o suporte |
| `POST /v1/submerchants/{merchantId}/document/upload-token` | `404` | `Representante legal não encontrado` | O `legalRepresentativeId` não pertence à subconta | Usar um `id` devolvido em `legalRepresentatives` ou na listagem de representantes |
| `POST /v1/document-uploads` | `401` | Sem token, ou `Token de upload inválido ou expirado` | Token ausente, com assinatura inválida ou vencido (300 segundos) | Emitir um novo token e enviar logo em seguida |
| `POST /v1/document-uploads` | `403` | `Token de upload expirado ou já utilizado` | Token de uso único já usado | Emitir um novo token |
| `POST /v1/document-uploads` | `413` | `FILE_TOO_LARGE`: `O arquivo excede o tamanho máximo de 50 MB.` | Arquivo acima de 50 MB. `details` traz `maxMb` e `actualMb` | Reduzir o arquivo |
| `POST /v1/document-uploads` | `415` | `UNSUPPORTED_FILE_TYPE`: `Tipo de arquivo não suportado. Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP).` | Tipo não aceito. `details` traz `allowed` e `actualType` | Enviar PDF ou imagem aceita |
| `POST /v1/document-uploads` | `400` | `NO_FILE_SENT`: `Nenhum arquivo foi enviado.` | Nenhum arquivo no `multipart/form-data` | Enviar o arquivo, com o nome do documento como nome do campo |
| `POST /v1/document-uploads` | `400` | `INVALID_DOCUMENT_NAME`: `Tipo de documento inválido para este envio.` | Nome de campo fora da lista | Usar um dos nomes de documento aceitos |
| `POST /v1/document-uploads` | `422` | `DOCUMENT_NOT_EDITABLE`: `Este documento não pode mais ser alterado no cadastro atual.` | Subconta já aprovada | Falar com o suporte |
| `GET /v1/submerchants/{merchantId}/legal-representatives` | `400` | Lista em `message` | `include` com valor diferente de `documents` | Enviar `include=documents` ou omitir |
| `GET /v1/submerchants/{merchantId}/legal-representatives` | `404` | `Merchant não encontrado` | A subconta não pertence à conta master autenticada | Conferir o `merchantId` |

Em `POST /v1/document-uploads`, os erros de arquivo vêm no formato `{ "error": "<CÓDIGO>", "message": "...", "details": { ... } }`, sem `statusCode`. Os erros do token (`401` e `403`) vêm no formato padrão.

### Taxas e dados da subconta

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | `401` | `Não autorizado` | Credencial inválida | Ver erros comuns |
| `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | `403` | `Fast Connect não habilitado para esta conta` | Connect não habilitado na conta master | Pedir a habilitação do Connect |
| `GET /v1/fast-connect/sub-accounts/{id}/fees-info` | `404` | `Subconta não encontrada` | `id` não vinculado à conta master, inexistente, ou o próprio id da conta master | Usar o `id` de uma subconta vinculada |

## Endpoints de webhook

| Rota | HTTP | Mensagem | Causa | Ação |
| - | - | - | - | - |
| `POST` e `PUT /v1/webhook-endpoints` | `400` | `URL inválida: informe um endereço http(s) público (endereços internos e reservados não são permitidos)` | URL interna, reservada ou mal formada. Na validação do corpo, chega em lista em `message` | Usar um endereço público |
| `POST` e `PUT /v1/webhook-endpoints` | `400` | `Este endereço é reservado e não pode ser usado como destino.` | Endereço reservado da plataforma | Usar outro endereço |
| `POST` e `PUT /v1/webhook-endpoints` | `400` | `Apenas contas master com FastConnect habilitado podem receber eventos das subcontas` | `include_submerchants` em conta sem Connect | Retirar `include_submerchants` |
| `POST` e `PUT /v1/webhook-endpoints` | `400` | Lista em `message` | Corpo inválido, como `enabled_events` que não é lista | Corrigir o corpo |
| `POST /v1/webhook-endpoints` | `403` | `Apenas administradores do gateway podem configurar endpoints de nível gateway` | Chamada sem `merchantId` na query | Enviar `?merchantId=` com o id da conta |
| Todas | `403` | `Acesso negado` | Conta sem acesso ao `merchantId`, ou perfil sem permissão de webhooks | Conferir o `merchantId` e o perfil de quem gerou a chave |
| Todas | `404` | `Merchant não encontrado` | `merchantId` inexistente | Conferir o `merchantId` |
| `PUT` e `DELETE /v1/webhook-endpoints/{webhookId}` | `404` | `Webhook não encontrado` | `webhookId` inexistente | Conferir o id na listagem |

## Veja também

> [card] [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md)
>
> Formato das respostas e quando repetir.

> [card] [Mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md)
>
> Todas as rotas e sua autenticação.

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> Recusas, bloqueios e disputas.

> [card] [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
>
> Permissões da chave e autenticação.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.