> ## 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.

# Erros e como tratar

> Formato das respostas de erro, o que cada código HTTP significa na API da Finvia e como decidir entre corrigir, consultar ou tentar de novo.

Quando uma requisição não dá certo, a API responde com um código HTTP e um corpo JSON que explica o motivo. Esta página mostra como ler esse corpo, o que cada código significa e qual reação o seu sistema deve ter. A lista completa de mensagens por rota está no [Catálogo de códigos de erro](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md).

> [!NOTE]
>
> **Para o negócio:** um bom tratamento de erros evita dois problemas para a operação: cobrar o cliente duas vezes (por repetir uma requisição que já tinha funcionado) e perder uma venda (por não mostrar ao cliente uma alternativa quando o cartão é recusado). Os dois casos estão cobertos abaixo.

## Formato da resposta de erro

A API usa três formatos de corpo de erro. O formato depende da rota e do tipo de erro, então o seu código precisa aceitar os três.

**1. Formato padrão**, com `statusCode`, `message` e `error`. É o da maior parte das rotas:

```json theme={null}
{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}
```

Nos erros de validação do corpo (campo ausente, tipo errado, valor fora do limite), o código é `400` e `message` vem como **lista** de textos, um por problema:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "shippingAddress.country must be a valid ISO31661 Alpha3 code"
  ],
  "error": "Bad Request"
}
```

O `401` vem só com `statusCode` e `message`: `{ "statusCode": 401, "message": "Unauthorized" }`.

| Campo | Tipo | O que contém |
| - | - | - |
| `statusCode` | integer | O mesmo código HTTP da resposta |
| `message` | string ou lista de strings | Descrição do problema. Em validação de campos, uma lista |
| `error` | string | Nome padrão do código HTTP (ex.: `Bad Request`, `Forbidden`, `Not Found`). Nem toda resposta traz |

**2. Formato com código de negócio**, com `code` e `message`, sem `statusCode`. Aparece nos erros de negócio do Apple Pay e na validação de cartão da criação de assinatura:

```json theme={null}
{
  "code": "CARD_VALIDATION_FAILED",
  "message": "Não foi possível validar o cartão: cobrança recusada."
}
```

| Onde | Códigos |
| - | - |
| Apple Pay (`/v1/apple-pay/*` e cobrança com Apple Pay) | `APPLE_PAY_INVALID_DOMAIN`, `APPLE_PAY_DOMAIN_NOT_VERIFIED`, `APPLE_PAY_RATE_LIMITED` e os demais listados no [catálogo](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md) |
| Validação do cartão em `POST /v1/subscriptions` (plano com trial grátis) | `CARD_VALIDATION_FAILED` (`422`), `CARD_VALIDATION_IN_PROGRESS` (`409`), `CARD_VALIDATION_RATE_LIMITED` (`429`) |

Nessas mesmas rotas, os erros de validação de campo e de permissão continuam no formato padrão.

**3. Formato do envio de documentos com token**, com `error`, `message` e `details`, sem `statusCode`. Aparece nos erros de arquivo de `POST /v1/document-uploads`:

```json theme={null}
{
  "error": "FILE_TOO_LARGE",
  "message": "O arquivo excede o tamanho máximo de 50 MB.",
  "details": { "maxMb": 50, "actualMb": 62.4 }
}
```

Nessa rota, os erros do token (`401` e `403`) voltam ao formato padrão.

> [!TIP]
>
> **Para o desenvolvedor:** decida o fluxo pelo código HTTP e, quando existir, pelo campo `code` (formato 2) ou `error` (formato 3). Use o `message` só para log e suporte. As mensagens misturam português e inglês (`Cobrança não encontrada`, `Insufficient balance. Required: X, Available: Y`) e podem mudar. Não faça comparação exata de texto para decidir regra de negócio.

```javascript Node.js theme={null}
// Lê os três formatos de erro e devolve um objeto único
function lerErro(status, corpo) {
  const mensagens = Array.isArray(corpo?.message) ? corpo.message : [corpo?.message].filter(Boolean);
  return {
    status,                                   // decida por aqui
    codigo: corpo?.code ?? (corpo?.statusCode ? undefined : corpo?.error), // formatos 2 e 3
    mensagens,                                // só para log
    detalhes: corpo?.details,
  };
}

console.log(lerErro(400, { statusCode: 400, message: ['amount must not be less than 1'], error: 'Bad Request' }));
console.log(lerErro(422, { code: 'CARD_VALIDATION_FAILED', message: 'Não foi possível validar o cartão: cobrança recusada.' }));
```

### Erro de permissão por perfil

A chave age com as permissões do usuário que a gerou. Quando o perfil desse usuário não tem permissão para a rota, a resposta é `403`:

```json theme={null}
{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }
```

Isso acontece, por exemplo, com chave gerada por usuário Desenvolvedor ao criar cobrança, em saldo e em saques, e com chave de Desenvolvedor ou Financeiro nas rotas de planos e assinaturas. 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).

### Resultados que não são erro HTTP

| Situação | Como aparece |
| - | - |
| Recusa de cartão | A cobrança é criada (`201`) com `status` `refused` ou `failed` e o motivo em `reason`. Também sai o webhook `charge.refused` ou `charge.failed` |
| 3D Secure obrigatório e não feito | A cobrança volta com `status` `refused` e `reason` com o código no início, como `3ds_required: ...` |
| Consulta de cobrança com `id` inexistente | `GET /v1/charges/{id}` responde hoje `200` com corpo vazio. Trate corpo vazio como "não encontrada" |

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "refused",
  "paymentDetails": null,
  "reason": "3ds_required: Não foi possível completar a autenticação 3DS obrigatória"
}
```

## Códigos HTTP usados pela API

### Sucesso

| Código | Significado | Onde aparece |
| - | - | - |
| `200` | Requisição atendida | Consultas, listagens, atualizações, ações de 3DS, cancelamento de assinatura, validação de domínio Apple Pay, atualização e exclusão de endpoint de webhook (sem corpo) |
| `201` | Recurso criado | Cobrança, estorno, cliente, cartão, plano, assinatura, subconta, token de upload, documentos, domínio Apple Pay, simulação de webhook de teste e saque. Em `POST /v1/payout-requests` e `POST /v1/webhook-endpoints`, o `201` vem **sem corpo**: o `id` se obtém na listagem |
| `204` | Atendida, sem corpo na resposta | `DELETE /v1/customers/{id}`, `POST /v1/subscription-plans/{id}/image` e `PATCH /v1/subscription-plans/{id}/status/confirm` |

> [!WARNING]
>
> `201` na criação de uma cobrança **não** significa pagamento aprovado. Leia o campo `status`: no cartão, ele pode vir `refused` ou `failed`. No Pix, vem `pending` até o cliente pagar.

### Erros do cliente (4xx)

O desenho abaixo resume a primeira coisa a conferir em cada código 4xx. Os exemplos de mensagem estão na tabela.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart LR
    Q{"Erro 4xx<br/>recebido"}:::decisao
    C400["400"]:::erro
    C401["401"]:::erro
    C403["403"]:::erro
    C404["404"]:::erro
    C409["409"]:::erro
    C413["413 · 415"]:::erro
    C422["422"]:::erro
    C429["429"]:::alerta
    A400["Corrija o corpo: message<br/>pode vir como lista"]:::neutro
    A401["Confira a chave, o Basic<br/>e os dois pontos no fim"]:::neutro
    A403["Confira o perfil de quem<br/>gerou a chave e o Connect"]:::neutro
    A404["Confira o id e se ele<br/>pertence à conta da chave"]:::neutro
    A409["CNPJ: consulte o cadastro<br/>Apple Pay: repita a chamada<br/>Cartão: espere a validação"]:::neutro
    A413["Envie PDF ou imagem<br/>de até 50 MB"]:::neutro
    A422["Leia o motivo e corrija<br/>a regra de negócio"]:::neutro
    A429["Aguarde. Não repita<br/>em laço"]:::neutro
    Q --> C400 --> A400
    Q --> C401 --> A401
    Q --> C403 --> A403
    Q --> C404 --> A404
    Q --> C409 --> A409
    Q --> C413 --> A413
    Q --> C422 --> A422
    Q --> C429 --> A429
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

| Código | Significado | Exemplos reais | O que fazer |
| - | - | - | - |
| `400` | Corpo inválido ou operação não permitida no estado atual | Lista em `message` (validação), `Shipping info must be provided for merchants selling physical items.`, `CVV is required when using cardTokenId`, `Invalid or expired confirmation token`, `Email already registered` | Corrija os dados ou o estado do recurso. Não repita igual |
| `401` | Credencial ausente ou inválida | `Unauthorized` (`Não autorizado` em `fees-info`) | Confira a chave, os dois pontos antes do Base64 e o prefixo `Basic `. Nas rotas com chave pública, confira se usou `pk_` |
| `403` | Sem permissão para a operação | `Acesso negado`, `Fast Connect not enabled.`, `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, `Redisparo de webhook disponível apenas para cobranças de teste` | Confira o perfil de quem gerou a chave. No Connect, confirme a habilitação. Saque não existe no Modo Teste |
| `404` | Recurso não encontrado ou fora do seu escopo | `Cobrança não encontrada`, `Customer not found`, `Subscription plan not found`, `SubMerchant not found`, `Merchant não encontrado`, `Merchant not found` | Confira o `id` e se ele pertence à conta da chave usada. No estorno, o `404` também indica cobrança que não está `paid` |
| `409` | Conflito | `Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.`, `APPLE_PAY_DOMAIN_ALREADY_REGISTERED`, `CARD_VALIDATION_IN_PROGRESS` | No CNPJ, consulte o cadastro existente. No Apple Pay, repita a chamada. Na validação de cartão, aguarde a primeira terminar |
| `413` e `415` | Arquivo grande demais ou de tipo não aceito (envio com token) | `FILE_TOO_LARGE`, `UNSUPPORTED_FILE_TYPE` | Envie PDF ou imagem (JPG, PNG, GIF, BMP ou WebP) de até 50 MB |
| `422` | Regra de negócio violada | `Fees not configured`, `Já existe um reembolso para esta cobrança`, `Insufficient balance. Required: X, Available: Y`, `CARD_VALIDATION_FAILED` | Leia o motivo, corrija a regra violada e só então envie de novo |
| `429` | Limite de tentativas atingido | `APPLE_PAY_RATE_LIMITED`, `CARD_VALIDATION_RATE_LIMITED` | Aguarde. Não repita em laço |

### Erros do servidor (5xx)

| Código | Significado | Exemplos reais | O que fazer |
| - | - | - | - |
| `500` | Erro interno | `Internal server error`, `APPLE_PAY_PROVIDER_AUTH_FAILED` | Em consultas, tente de novo com espera crescente. Em criações, verifique antes se o recurso foi criado. Se persistir, fale com o suporte |
| `501` | Operação não disponível para o método ou provedor | `Reembolso não implementado para este método de pagamento`, `Reembolso não disponível para este provedor de pagamento` | Não repita. Fale com o suporte |
| `503` | Serviço indisponível | `APPLE_PAY_PROVIDER_UNAVAILABLE` | Tente de novo mais tarde, com espera crescente |

## Quando repetir uma requisição

O desenho abaixo mostra quando repetir uma requisição, conforme o código recebido e o tipo de operação.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    R(["Resposta da API<br/>ou timeout"]):::neutro
    Q{"Código HTTP"}:::decisao
    S2["Concluída, não repita<br/>na cobrança, leia o status"]:::ok
    S4["Nada foi feito<br/>corrija antes de reenviar"]:::erro
    Q409{"Registro de domínio<br/>Apple Pay?"}:::decisao
    AP["Repita: volta o<br/>registro existente"]:::ok
    S429["Espere e repita"]:::alerta
    QG{"É consulta<br/>GET?"}:::decisao
    RG["Repita com espera<br/>crescente: 1, 2 e 4 s"]:::alerta
    VER["Verifique se o efeito<br/>aconteceu e só repita<br/>se não aconteceu"]:::alerta
    S501["Não repita<br/>fale com o suporte"]:::erro
    R --> Q
    Q -->|"2xx"| S2
    Q -->|"400 · 401 · 403<br/>404 · 422"| S4
    Q -->|"409"| Q409
    Q409 -->|"sim"| AP
    Q409 -->|"não"| S4
    Q -->|"429"| S429
    Q -->|"500 · 503<br/>ou timeout"| QG
    QG -->|"sim"| RG
    QG -->|"não: criação<br/>ou ação"| VER
    Q -->|"501"| S501
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

| Resultado | Consulta (`GET`) | Criação ou ação (`POST`, `PUT`, `PATCH`, `DELETE`) |
| - | - | - |
| `2xx` | Concluída | Concluída. Não repita |
| `400`, `401`, `403`, `404`, `422` | Não repita sem corrigir | Não repita sem corrigir. Nada foi feito |
| `409` | Não se aplica | No registro de domínio Apple Pay, repita: a API devolve o registro existente. Nos demais casos, corrija antes |
| `429` | Repita depois de esperar | Repita depois de esperar |
| `500`, `503` ou timeout | Repita com espera crescente | **Verifique primeiro** se o efeito aconteceu. Só repita se não aconteceu |
| `501` | Não repita | Não repita. A operação não existe para aquele método ou provedor |

> [!WARNING]
>
> A API não tem `Idempotency-Key`: antes de repetir um `POST /v1/charges` depois de um `500` ou timeout, siga o procedimento em [Idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência).

## Como tratar no código

```javascript Node.js theme={null}
class FinviaError extends Error {
  constructor(status, corpo) {
    const msg = Array.isArray(corpo?.message) ? corpo.message.join('; ') : corpo?.message;
    super(msg || `HTTP ${status}`);
    this.status = status;
    this.codigo = corpo?.code ?? (corpo?.statusCode ? undefined : corpo?.error);
    this.corpo = corpo;
  }
}

async function chamarFinvia(metodo, rota, corpo) {
  const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 60000); // o cartão é processado de forma síncrona

  try {
    const res = await fetch(`https://api-global.fastpaybrasil.com${rota}`, {
      method: metodo,
      headers: {
        Authorization: `Basic ${credentials}`,
        'Content-Type': 'application/json',
      },
      body: corpo ? JSON.stringify(corpo) : undefined,
      signal: controller.signal,
    });

    // 204 não tem corpo
    const texto = await res.text();
    const json = texto ? JSON.parse(texto) : null;

    if (!res.ok) {
      console.error('Erro Finvia', { metodo, rota, status: res.status, corpo: json });
      throw new FinviaError(res.status, json);
    }
    return json;
  } finally {
    clearTimeout(timer);
  }
}

async function comRetentativa(fn, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    try {
      return await fn();
    } catch (e) {
      const transitorio = e.name === 'AbortError' || e.status >= 500 || e.status === 429;
      if (!transitorio || i === tentativas - 1) throw e;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); // 1 s, 2 s, 4 s
    }
  }
}

// Consultas podem usar retentativa direta.
// GET /v1/charges/{id} com id inexistente responde 200 com corpo vazio (json === null).
const cobranca = await comRetentativa(() => chamarFinvia('GET', `/v1/charges/${id}`));
if (!cobranca) console.log('Cobrança não encontrada');

// Criações não: em caso de 5xx ou timeout, verifique antes de repetir.
```

### Recusa de cartão: trate como resultado de negócio

```javascript Node.js theme={null}
const charge = await chamarFinvia('POST', '/v1/charges', pedido);

switch (charge.status) {
  case 'paid':
    // Aprovada
    break;
  case 'refused':
  case 'failed':
    // Mostre uma mensagem amigável e ofereça Pix ou outro cartão.
    // Guarde charge.reason no log para análise.
    break;
  case 'pending':
    // Pix: mostre o QR Code e aguarde o webhook charge.paid
    break;
  default:
    // in_analysis, authentication_required e outros: aguarde a notificação
    break;
}
```

## Boas práticas

* **Registre o corpo completo do erro** com rota, método, código HTTP e horário. Sem dados de cartão e sem a chave.
* **Não repita erros `4xx`** sem corrigir a causa. Eles indicam que nada foi feito.
* **Repita `5xx` e timeouts só com verificação prévia** nas operações que criam ou alteram algo.
* **Use espera crescente** entre tentativas (por exemplo, 1, 2 e 4 segundos) e um limite de tentativas.
* **Defina um timeout** nas suas chamadas para não deixar o checkout preso.
* **Separe mensagem técnica de mensagem ao cliente.** O `message` da API vai para o log. O cliente vê um texto amigável com a próxima ação possível.
* **Monitore a taxa de erros** por rota. Um aumento de `401` pode indicar chave trocada; de `403`, permissão do usuário que gerou a chave; de `422`, mudança na configuração da conta ou no payload enviado.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` em todas as rotas | Base64 sem os dois pontos, chave errada ou ambiente trocado | Decodifique o cabeçalho e confira se termina em `:` |
| `401` só nas rotas de 3DS | Chave secreta usada onde o contrato pede a chave pública | Use `pk_` nas rotas `/v1/three-ds/*` e em `resume-3ds` |
| `403` com `Acesso negado` ao criar cobrança ou assinatura | Perfil do usuário que gerou a chave | 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) |
| `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie `shippingAddress` com `postalCode`, `addressLine1`, `city`, `state` e `country` |
| `404` com `Cobrança não encontrada` no estorno | A cobrança não está `paid` (pendente, já estornada ou em chargeback) | Consulte a cobrança antes de pedir o estorno |
| `422` com `Já existe um reembolso para esta cobrança` | Segundo pedido de estorno da mesma cobrança | Não repita. Consulte a cobrança |
| `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Saque pedido com a chave de teste | Saques só existem em produção |
| O código quebra ao ler `message` | Em erros de validação, `message` é uma lista | Trate `message` como texto ou lista |
| Erro tratado como sucesso | O código leu só `201` e ignorou `status` | Sempre leia `status` na resposta da cobrança |

## Perguntas frequentes

> [accordion] A recusa do cartão aparece como erro HTTP?
>
> Não. A cobrança é criada com `201`, e o `status` vem `refused` ou `failed`, com o motivo em `reason`. Trate como resultado de negócio e ofereça outra forma de pagamento.

> [accordion] Posso mostrar o message da API para o cliente final?
>
> Não é recomendado. As mensagens são técnicas e misturam português e inglês. Mostre um texto próprio e guarde o `message` no log. A exceção é o `CARD_VALIDATION_FAILED`, cujo `message` foi feito para exibição.

> [accordion] Recebi 500 ao criar uma cobrança. A cobrança existe?
>
> Pode existir. Antes de repetir, siga a verificação descrita em [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).

> [accordion] Onde vejo todas as mensagens possíveis de uma rota?
>
> No [Catálogo de códigos de erro](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md), agrupado por rota, e na página de referência de cada rota.

## Como testar

* Envie uma requisição sem o cabeçalho `Authorization` e confira o tratamento do `401`.
* Envie um item `physical` sem `shippingAddress` e confira o tratamento do `400` (cenário **CHG-10**).
* Envie um corpo com um campo obrigatório faltando e confira se o seu código lê `message` como lista.
* Consulte um `id` inexistente em `GET /v1/charges/{id}` e confira se o seu código trata o `200` com corpo vazio.
* Crie uma cobrança com o cartão de teste `4444333322221112` e confira o tratamento de `refused` (cenário **CHG-03** do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)).
* Em split, comprove que a sua integração trata a rejeição de percentual inválido e de `merchantId` fora do grupo (cenários **SPL-03** e **SPL-04**).

## Veja também

> [card] [Catálogo de códigos de erro](https://docs.fastpaybrasil.com/anexos/codigos-de-erro.md)
>
> Todas as mensagens literais, por rota.

> [card] [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)
>
> Como repetir sem duplicar.

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

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> O que fazer em cada status.


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