> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

# Erros da API

A API GTFgts tem **duas categorias de erro distintas**, que não devem ser confundidas:

1. **Erros de borda** — falhas da própria requisição HTTP (validação, autenticação, rate limit, indisponibilidade). Seguem o padrão [RFC 7807](https://tools.ietf.org/html/rfc7807) (`application/problem+json`), com os campos `type` (uma URI que aponta para a **seção correspondente desta página** — use o fragmento após `#` para tratamento programático), `title`, `status`, `detail`, `instance` e as extensões proprietárias `errorCode` (código canônico GTLab estável) e `timestamp`.
2. **Erro de operação (`OperationError`)** — o desfecho de uma operação FGTS que falhou. **Não** é um `ProblemDetail`: aparece apenas no campo `error` do polling e do webhook. Ver [Erro de operação (OperationError)](#operationerror).

Use o `errorCode` (erros de borda) ou o `code` (erro de operação) para tratar erros de forma programática. O [Catálogo de códigos](#catalogo) no fim desta página reúne todos os códigos em tabelas, com o que fazer em cada caso.

{% hint style="info" %}
Três exceções ao formato acima, para o seu parser não quebrar:

* **Rota inexistente, método não suportado (`405`), `Content-Type` diferente de `application/json` (`415`) e `Accept` incompatível (`406`)** saem no formato padrão do framework: `type: about:blank` e **sem** `errorCode` nem `timestamp`. Trate pelo status HTTP.
* Os `409` da [retentativa de averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) saem sem `type`, `instance` e `message`; o `errorCode` está presente.
* Um `401` em rota fora de `/api/v1/fgts/**`, `/api/v1/simulations/**` e `/api/v1/webhooks/**` sai sem corpo.
  {% endhint %}

***

## Erro de Validação <a href="#validation-error" id="validation-error"></a>

**HTTP 400.** Campos do request não atendem às regras de validação (obrigatório, formato, tamanho — ex.: CPF fora do padrão `^\d{11}$`, ou uma `webhookUrls` que não começa com `https://`). `errorCode: VALIDATION_ERROR`.

O `ProblemDetail` de validação inclui o campo extra **`errors`** — um mapa `campo → mensagem` com o detalhe de cada campo inválido:

```json
{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#validation-error",
  "title": "Bean validation error",
  "status": 400,
  "detail": "One or more fields were invalid. See 'errors' for details.",
  "errorCode": "VALIDATION_ERROR",
  "errors": { "cpf": "CPF must be exactly 11 digits", "webhookUrls[0]": "must be a valid URL" },
  "timestamp": "2026-06-14T12:00:00Z"
}
```

Como ler o `errors`:

* **A chave é o caminho do campo**, com pontos e índices: `borrower.cpf`, `installments[0].dueDate`, `webhookUrls[2]`. Para parâmetro de URL ou header inválido, a chave é o nome do parâmetro (`contractNumber`, `requestId`, `reserveIdentifier`, `simulationId`).
* **Duas violações no mesmo campo** chegam concatenadas na mesma mensagem, separadas por `;` .
* Na [coerência de valores do contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/submeter-contrato.md), as chaves ficam **na raiz** — `disbursementAmount`, `contractAmount`, `financedAmount`, `totalInterest`, `iofAmount`, `tacAmount` — com a mensagem `(received X, expected Y)`.
* Nas **regras de exclusividade** — informar exatamente um entre `contractNumber` e `reserveIdentifier` no [encerramento de reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-cancelamento-reserva.md); PIX **ou** conta bancária na [revisão da conta de desembolso](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/revisar-conta-desembolso.md) — o `errors` hoje vem **vazio** (`{}`). A causa está em `detail`.

O `title` muda com a origem do 400, e o `errorCode` continua `VALIDATION_ERROR` nos três casos:

| `title`                 | Quando                                                                                                                                                                                            | `errors`                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `Bean validation error` | Campo, parâmetro de URL ou header fora do padrão.                                                                                                                                                 | Sim                                     |
| `Malformed request`     | Corpo ausente ou JSON inválido (`detail: Request body is missing or malformed.`), ou valor de tipo errado num campo — data, número, enum (`detail: Invalid value for field '<campo>': <razão>.`). | Só no tipo errado, com a chave do campo |
| `Bad Request`           | Header `Idempotency-Key` ausente em `POST /api/v1/fgts/contracts` (`detail: Required header is missing: Idempotency-Key`).                                                                        | Não                                     |

{% hint style="info" %}
O `errors` também aparece fora da validação: em `CCB_VALIDATION_FAILED`, `CONTRACT_CLIENT_REFERENCE_ALREADY_EXISTS`, `CONTRACT_INSTALLMENTS_MISMATCH`, `CONTRACT_FIRST_DUE_DATE_MISMATCH` e nos códigos repassados do serviço de formalização (ver [Erros de formalização de contrato](#formalizacao)). Leia `errors` sempre que vier, não só em `VALIDATION_ERROR`.
{% endhint %}

***

## Não Autenticado <a href="#not-authenticated" id="not-authenticated"></a>

**HTTP 401.** JWT ausente, inválido, expirado ou revogado. Inclua o token no header `Authorization: Bearer <token>`. `errorCode: UNAUTHORIZED`.

Uma falha transitória da plataforma ao validar o token também responde `401`. Se o token é sabidamente válido, repita com backoff antes de renová-lo ou escalar.

***

## Acesso Negado <a href="#forbidden" id="forbidden"></a>

**HTTP 403.** Autenticado, mas sem permissão para o recurso. Ocorre **apenas** na consulta de operação (`GET /api/v1/fgts/operations/{requestId}`) com um `requestId` de outro originator. `errorCode: ORIGINATOR_OWNERSHIP_VIOLATION`.

Contrato, reserva e simulação de outro originator **não** respondem `403`: respondem `404`, para não revelar que o recurso existe. Ver [Recurso Não Encontrado](#resource-not-found).

***

## Recurso Não Encontrado <a href="#resource-not-found" id="resource-not-found"></a>

**HTTP 404.** O recurso solicitado não existe dentro do seu escopo. O `errorCode` indica o tipo de recurso:

| `errorCode`                              | Recurso                       | Rotas                                                                                                                                                                 |
| ---------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPERATION_NOT_FOUND`                    | Operação (`requestId`)        | `GET` e `DELETE /api/v1/fgts/operations/{requestId}`                                                                                                                  |
| `CONTRACT_NOT_FOUND`                     | Contrato (`contractNumber`)   | Todas as rotas `/api/v1/fgts/contracts/{contractNumber}/**`                                                                                                           |
| `GUARANTEE_NOT_FOUND`                    | Reserva (`reserveIdentifier`) | [Retentativa de averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) |
| `SIMULATION_NOT_FOUND`                   | Simulação                     | `GET /api/v1/simulations/{simulationId}`                                                                                                                              |
| `WEBHOOK_SUBSCRIPTION_NOT_FOUND`         | Cadastro de webhook           | `GET`, `PUT` e `DELETE /api/v1/webhooks`                                                                                                                              |
| `CONTRACT_DOCUMENT_NOT_AVAILABLE`        | CCB gerada                    | `GET .../documents/template`                                                                                                                                          |
| `CONTRACT_SIGNED_DOCUMENT_NOT_AVAILABLE` | PDF assinado                  | `GET .../documents/signed`                                                                                                                                            |

Contrato, reserva ou simulação **de outro originator** também respondem `404`, com o mesmo `errorCode` de recurso inexistente.

Logo depois do `202` de uma averbação, de um cancelamento de reserva ou de uma manutenção de garantia, o `GET` da operação pode responder `404 OPERATION_NOT_FOUND` por alguns segundos, enquanto a operação é registrada. Repita a consulta em seguida antes de concluir que o `requestId` não existe.

Um **protocolo inexistente** não gera `404`: a [consulta de status por protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md) é assíncrona e o desfecho chega no polling. Uma operação **recusada** na admissão do processamento (averbação duplicada, recusa de gate) também **não** gera `404`: ela é consultável no polling e responde `200` com `status = FAILED` — ver [Recusas de duplicidade e `originalRequestId`](#originalrequestid).

***

## Conflito <a href="#conflict" id="conflict"></a>

**HTTP 409.** A requisição conflita com o estado atual do recurso. O `errorCode` identifica o conflito:

* `WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS` — já existe cadastro de webhook para o originator (`POST /api/v1/webhooks`). Use `PUT` para alterá-lo.
* `CONFLICT` — violação de unicidade detectada só no momento da gravação (ex.: dois cadastros de webhook simultâneos). Consulte o recurso e decida.
* `OPERATION_NOT_CANCELLABLE` — tentativa de cancelar (`DELETE /api/v1/fgts/operations/{requestId}`) uma operação que já saiu de `QUEUED`, **ou** uma averbação, manutenção de garantia ou cancelamento de reserva — que não são canceláveis pelo cliente em nenhum estado. Os dois casos têm o mesmo `detail`.
* `CONTRACT_NO_ACTIVE_RESERVATION` — encerramento (`POST .../reserve-cancellations`) ou manutenção (`POST .../guarantee-maintenances`) de um contrato que não tem reserva ativa.
* `ENDORSEMENT_RETRY_LIMIT_EXCEEDED` — [retentativa de averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) (`POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`) recusada porque o **teto de 3 retentativas** da reserva já foi atingido (4 tentativas no total, contando a averbação original). Este `409` **não incrementa o contador** — a chamada recusada não gasta uma das tentativas permitidas, então repeti-la é inofensivo para o orçamento de retentativas (e continuará sendo recusada).
* `ENDORSEMENT_NOT_RETRYABLE` — [retentativa de averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) recusada porque a reserva **não está num estado de falha** retentável: está em processamento (inclusive dentro da [retentativa automática](#retrying)), já averbada, quitada ou cancelada — ou foi recusada antes de chegar à Caixa, por `reserveIdentifier` duplicado. Toda recusa **da Caixa** é retentável; o que não é retentável é uma reserva que não falhou, ou que falhou sem que a Caixa chegasse a recebê-la.
* `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` — [retentativa de averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) recusada porque a reserva é anterior ao formato atual de períodos e não pode ser reprocessada automaticamente. Submeta uma averbação nova.

Os conflitos de contrato (`CONTRACT_*`, `ACCOUNT_AMENDMENT_IN_FLIGHT`) estão em [Erros de formalização de contrato](#formalizacao).

{% hint style="warning" %}
Os três códigos `ENDORSEMENT_*` acima aparecem **como `errorCode` de um `409`** apenas na retentativa **por identificador de reserva**. Na [retentativa por contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md) (`POST /api/v1/fgts/contracts/{contractNumber}/endorsement-retries`) a resposta é `202` e a recusa chega **depois, pelo webhook** `CONTRACT_ENDORSEMENT_REJECTED` — mas com **os mesmos códigos**, agora no `OperationError` do evento, em `data.error.code`. Ou seja: a recusa por teto continua distinguível de uma recusa da Caixa, só que por webhook em vez de resposta HTTP. Contrato fora de `ENDORSEMENT_REJECTED` responde `409 CONTRACT_INVALID_STATUS`.
{% endhint %}

***

## Rate Limit Excedido <a href="#rate-limit-exceeded" id="rate-limit-exceeded"></a>

**HTTP 429.** Dois limites diferentes, distinguidos pelo `errorCode`:

| `errorCode`                   | Onde                                                                                                                                                                                                                                                                                | Resposta                                                                                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INGRESS_RATE_LIMIT_EXCEEDED` | Todas as submissões de operação FGTS (`POST /api/v1/fgts/balance-queries`, `.../batch/balance-queries`, `.../endorsements`, `.../reserve-cancellations`, `.../guarantee-maintenances`, `.../reserved-value-queries`, `.../reserve-protocol-queries`, `.../protocol-status-queries`) | Header `Retry-After: 1`. **Sem** headers `X-RateLimit-*`. Nenhum `requestId` é gerado.                                                                                           |
| `RATE_LIMIT_EXCEEDED`         | Contratos — `POST /api/v1/fgts/contracts`, `POST .../documents`, `PUT .../disbursement-account`, `POST .../payment-approval` (**30 req/min**) — e `POST /api/v1/webhooks` (**25 req/min**)                                                                                          | Headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (**epoch em milissegundos**) e `Retry-After`; propriedades `retryAfter`, `limit` e `resetAt` no corpo. |

Os dois limites são **por originator**, não por usuário nem por IP.

Nas submissões FGTS, requisições acima da cota normal mas abaixo do limite são **admitidas** com prioridade `DEFERRED` e retornam `202`. Ver [Prioridades e rate limit](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md).

{% hint style="info" %}
O valor `RATE_LIMITED` do `protocolStatus` (no `result` de uma [consulta de status por protocolo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/consultar-status-protocolo.md) concluída) indica que a **Caixa** limitou aquela consulta — é um estado retornado no resultado da operação assíncrona, **não** um erro HTTP de borda.
{% endhint %}

***

## Regra de Negócio <a href="#business-rule-violation" id="business-rule-violation"></a>

**HTTP variável.** Violação de regra de negócio na admissão da requisição; o status HTTP depende da regra e o `errorCode` identifica a regra específica. Exemplos: `CET_ABOVE_MAXIMUM` (422, CET anual da simulação acima de 9999,999999% — ver [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md#cet-acima-do-teto)), `ORIGINATOR_CODE_NOT_ASSIGNED` (422, originator sem código cadastrado na averbação — acione a Giro), `IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` (422, `Idempotency-Key` reusada com outro corpo — ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md#payload-diferente)). A lista completa está no [Catálogo de códigos](#catalogo-borda). Regras de recurso inexistente ou conflito são tratadas nas seções [Recurso Não Encontrado](#resource-not-found) e [Conflito](#conflict).

***

## Erro Interno <a href="#internal-error" id="internal-error"></a>

**HTTP 500.** Erro inesperado no servidor. `errorCode: INTERNAL_ERROR`. Repita **uma vez** com o mesmo corpo e a mesma `Idempotency-Key`; se persistir, acione o suporte informando o `timestamp` da resposta.

***

## Serviço Indisponível <a href="#upstream-unavailable" id="upstream-unavailable"></a>

**HTTP 503.** Serviço temporariamente indisponível; a requisição **não** foi aceita. Cenários distinguidos pelo `errorCode`:

| `errorCode`                          | Onde                                                                                                                                                                                                                                                                              | `Retry-After`                                                                   |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `SUBMISSION_TEMPORARILY_UNAVAILABLE` | Submissões de operação FGTS, todas as rotas `/api/v1/fgts/contracts/**` e, em indisponibilidade momentânea da plataforma, **qualquer rota**                                                                                                                                       | `5`                                                                             |
| `DISPATCHER_UNAVAILABLE`             | **Somente** `GET` e `DELETE /api/v1/fgts/operations/{requestId}` — não ocorre nas submissões                                                                                                                                                                                      | `30`                                                                            |
| `GUARANTEE_LEDGER_UNAVAILABLE`       | [Retentativa de averbação por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) e `GET /api/v1/fgts/operations/{requestId}` de averbação, cancelamento de reserva ou manutenção de garantia | `60` (indisponível) ou `5` (sobrecarga); também em `retryAfterSeconds` no corpo |
| `UPSTREAM_UNAVAILABLE`               | Simulações (`/api/v1/simulations/**`)                                                                                                                                                                                                                                             | **Não envia** — use backoff próprio                                             |
| `CAIXA_MAINTENANCE_WINDOW`           | Só a [consulta de saldo](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo.md) (`POST /api/v1/fgts/balance-queries`)                                                                                      | Segundos até `maintenanceEndsAt` — ver [abaixo](#caixa-maintenance-window)      |

Repita com o mesmo corpo e a mesma `Idempotency-Key` depois do intervalo indicado.

### `SUBMISSION_TEMPORARILY_UNAVAILABLE` <a href="#service-unavailable" id="service-unavailable"></a>

Indisponibilidade momentânea da plataforma ao registrar a requisição. Nada foi gravado: repetir com a mesma `Idempotency-Key` depois do `Retry-After` não gera duplicata. É o código também quando o serviço de formalização está indisponível — na submissão de contrato, na aprovação de pagamento e no encerramento por contrato.

### Janela de manutenção da Caixa <a href="#caixa-maintenance-window" id="caixa-maintenance-window"></a>

Quando a Caixa entra em manutenção programada, `POST /api/v1/fgts/balance-queries` responde `503` com `errorCode: CAIXA_MAINTENANCE_WINDOW` e **um campo a mais** no `ProblemDetail`:

| Campo                  | Significado                                 |
| ---------------------- | ------------------------------------------- |
| `maintenanceEndsAt`    | Fim previsto da janela, em UTC (ISO-8601).  |
| `Retry-After` (header) | Segundos restantes até `maintenanceEndsAt`. |

```json
{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Caixa is under scheduled maintenance until 2026-08-30T11:00:00Z. Retry after that instant.",
  "errorCode": "CAIXA_MAINTENANCE_WINDOW",
  "maintenanceEndsAt": "2026-08-30T11:00:00Z",
  "timestamp": "2026-08-30T05:00:00Z"
}
```

Três pontos que mudam como integrar:

* **A requisição não foi enfileirada** e nenhuma chave de idempotência foi consumida. Reenviar o mesmo corpo com a mesma `Idempotency-Key` depois da janela produz uma consulta nova, não uma duplicata.
* **`maintenanceEndsAt` é um limite superior, não uma promessa.** A janela pode ser encerrada antes quando a Caixa volta mais cedo; nesse caso a consulta volta a ser aceita antes do horário informado.
* **Só a consulta interativa é recusada.** [`POST /api/v1/fgts/batch/balance-queries`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-consulta-saldo-lote.md), averbação e as demais operações continuam sendo aceitas normalmente e são processadas quando a janela fecha — não é preciso represá-las do seu lado.

***

## Erros de formalização de contrato <a href="#formalizacao" id="formalizacao"></a>

Os endpoints de **contrato** (`/api/v1/fgts/contracts/**` — ver [Contratos (Formalização)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos.md)) têm `errorCode` específicos, além dos genéricos de borda (`VALIDATION_ERROR`, `UNAUTHORIZED`, `RATE_LIMIT_EXCEEDED`, `SUBMISSION_TEMPORARILY_UNAVAILABLE`, `INTERNAL_ERROR`). A tabela completa, com rota e ação, está no [Catálogo de códigos](#catalogo-contrato). Erros do **processo** de formalização (averbação negada, falha no provedor) **não** são erros de borda; chegam no campo `error` dos eventos de webhook — ver [Erro no campo `error` dos eventos de formalização](#error-eventos-formalizacao).

**HTTP 400** — corpo do contrato inválido:

* `VALIDATION_ERROR` — campo fora do padrão (CPF, valores, datas), header `Idempotency-Key` ausente, ou regra de pagamento violada. O corpo de pagamento é **flat**: o discriminador `payoutType` (`PIX` ou `BANK_ACCOUNT`) define **exatamente um** conjunto de campos — ou `pixKey`/`pixKeyType`, ou `bankCode`/`branch`/`accountNumber`/`accountDigit`/`accountType`. Também é `VALIDATION_ERROR` o **PDF inválido** em `signedDocumentBase64` (Base64 inválido, inclusive com prefixo `data:`; conteúdo sem o cabeçalho `%PDF-`; ou acima de **10 MiB** decodificado), com o motivo em `errors.signedDocumentBase64`.
* `CONTRACT_DOCUMENT_REQUIRED` — `generateDocument=false` em `POST /api/v1/fgts/contracts` sem `signedDocumentBase64`. No `POST .../documents`, o campo ausente responde `VALIDATION_ERROR`.
* `CONTRACT_DOCUMENT_UNEXPECTED` — `generateDocument=true` com `signedDocumentBase64` preenchido. Escolha um dos dois modos.
* `CONTRACT_FIRST_DUE_DATE_MISMATCH` — `financialTerms.firstDueDate` diferente da menor `installments[].dueDate`.
* `CONTRACT_INSTALLMENTS_MISMATCH` — `installmentCount` diferente do número de itens em `installments[]`.
* `CCB_VALIDATION_FAILED` — a validação prévia da CCB no emissor recusou os dados; os campos estão em `errors`.
* `PAYMENT_PROOF_UNSUPPORTED_CONTENT_TYPE` — no [encerramento por contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md), `paymentProof.contentType` diferente de `application/pdf`, `image/png` e `image/jpeg`.
* `PAYMENT_PROOF_INVALID_BASE64` — `paymentProof.contentBase64` não é Base64 válido (mesmo depois de descartar o prefixo `data:<tipo>;base64,` e as quebras de linha).
* `PAYMENT_PROOF_CONTENT_MISMATCH` — o conteúdo de `paymentProof.contentBase64` não é do tipo declarado em `contentType` (ex.: imagem PNG enviada como `application/pdf`).

**HTTP 404** (`errorCode: CONTRACT_NOT_FOUND`) — `contractNumber` inexistente **ou fora do escopo do token**. O acesso a um contrato de outro originator retorna `404` (não `403`). `GET .../documents/template` retorna `404 CONTRACT_DOCUMENT_NOT_AVAILABLE` enquanto a CCB não foi gerada — inclusive com o contrato em `DOCUMENT_GENERATION_FAILED`, até que a geração seja concluída (webhook `CONTRACT_DOCUMENT_GENERATED`). `GET .../documents/signed` retorna `404 CONTRACT_SIGNED_DOCUMENT_NOT_AVAILABLE` enquanto o PDF assinado não foi anexado (Modo B em `AWAITING_SIGNED_DOCUMENT`).

**HTTP 409** — conflito com o estado atual do contrato; o `errorCode` identifica o conflito:

* `CONTRACT_IDEMPOTENCY_CONFLICT` — **idempotência divergente** (reenvio da mesma `Idempotency-Key` com **payload diferente** do original) ou **documento fora de estado** (`POST .../documents` quando o contrato **não está em `AWAITING_SIGNED_DOCUMENT`** — Modo B já concluído, ou submetido em Modo A). No `POST .../documents`, consulte o contrato antes de reenviar.
* `CONTRACT_NOT_CANCELLABLE` — contrato **não cancelável**: `DELETE .../contracts/{contractNumber}` sobre um contrato já pago ou em **estado terminal** (`DISBURSED`, `CANCELLED`, `FORMALIZATION_FAILED`, `REVERSAL_FAILED`). Desde 2026-09-23, `PENDING_CCB_CONFIRMATION` e `PENDING_DISBURSEMENT` são canceláveis (ver [Cancelar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/cancelar-contrato.md)).
* `CONTRACT_NOT_PENDING_PAYMENT_APPROVAL` — `POST .../payment-approval` sobre contrato fora de `PENDING_PAYMENT_APPROVAL`.
* `CONTRACT_NOT_IN_REVISION` — **sem revisão de desembolso aberta**: `PUT .../disbursement-account` quando não há revisão em andamento (conta não-revisável ou prazo expirado).
* `ACCOUNT_AMENDMENT_IN_FLIGHT` — **ajuste de conta ainda em curso**: `PUT .../disbursement-account` quando um ajuste anterior do mesmo contrato ainda não foi respondido pelo provedor, ou terminou sem resposta definitiva. Consulte `disbursement.phase` em [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) e reenvie só quando a fase deixar de ser `ACCOUNT_AMENDMENT_IN_FLIGHT`.
* `CONTRACT_INVALID_STATUS` — **contrato fora do estado elegível** para a operação pedida: `POST .../endorsement-retries` sobre um contrato que **não está em `ENDORSEMENT_REJECTED`** (só contratos com averbação recusada admitem [retentativa](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md)).
* `CONTRACT_NO_ACTIVE_RESERVATION` — encerramento ou manutenção de garantia de contrato sem reserva ativa.

**HTTP 413** (`errorCode: PAYLOAD_TOO_LARGE`) — em qualquer rota, o corpo da requisição passa de **15 MiB**. A requisição é recusada antes de ser lida por inteiro e nada é registrado. Se o corpo for enviado em `Transfer-Encoding: chunked`, a conexão é encerrada sem resposta HTTP.

**HTTP 413** (`errorCode: PAYMENT_PROOF_TOO_LARGE`) — no [encerramento por contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/encerramento/submeter-solicitacao.md), o comprovante em `paymentProof` passa de **5 MiB** decodificado. A solicitação não é registrada: reduza o arquivo e reenvie. O PDF da CCB **não** usa este código — acima do limite dele, a resposta é `400 VALIDATION_ERROR`.

**HTTP 422** — regra de negócio na submissão ou na revisão:

* `CONTRACT_CLIENT_REFERENCE_ALREADY_EXISTS` — `clientReference` já usado por outro contrato do originator. `errors.clientReference` informa qual. Use referência única, ou consulte o contrato existente.
* `CONTRACT_NUMBER_ALREADY_EXISTS` — o `contractNumber` informado já existe para o originator. Informe outro, ou omita o campo para a plataforma gerar.
* `CONTRACT_NUMBER_ALLOCATION_EXHAUSTED` — com `contractNumber` omitido, a plataforma não encontrou número livre. Acione o suporte.
* `FORMALIZATION_CONFIG_NOT_PROVISIONED`, `FORMALIZATION_CONFIG_INCOMPLETE`, `GTBANKER_CREDENTIAL_NOT_FOUND` — o originator ainda não está configurado para formalizar. Não é erro do payload; acione a Giro.
* `DISBURSEMENT_ACCOUNT_REJECTED` — na **revisão da conta de desembolso** (`PUT .../disbursement-account`), o provedor **recusou a nova conta** informada. Corrija os dados da conta (PIX ou bancária) e reenvie.

**Outros 4xx** (`errorCode: CONTRACT_REQUEST_REJECTED`) — o serviço de formalização recusou a requisição e não informou um código próprio. Quando ele informa, o `errorCode` dele é repassado como está, e o `errors` também. Um `contractNumber` de path com mais de 8 dígitos chega por aqui, como `400`. Se vier sem `errors`, acione o suporte.

**HTTP 429** (`errorCode: RATE_LIMIT_EXCEEDED`) — rate limit dos endpoints de contrato excedido (**30 req/min**). Ver [Rate Limit Excedido](#rate-limit-exceeded).

**HTTP 503** (`errorCode: SUBMISSION_TEMPORARILY_UNAVAILABLE`) — serviço de formalização temporariamente indisponível. Aguarde os segundos indicados no header `Retry-After` (`5`) e tente novamente.

### Erro no campo `error` dos eventos de formalização <a href="#error-eventos-formalizacao" id="error-eventos-formalizacao"></a>

Alguns eventos de webhook `CONTRACT_*` trazem um nó **`error`** com a causa da falha. Esse `error` **não** é um `ProblemDetail` nem um `errorCode` de borda:

| Evento                                | `error.code`                                                                                                                                                                                                                                                                                            | Onde está a causa                                   |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `CONTRACT_ENDORSEMENT_REJECTED`       | Código canônico da recusa — ex.: `ENDORSEMENT_DENIED`, `OPERATION_NOT_YET_ALLOWED` ([Recusa por data](#operation-not-yet-allowed)) — ou o motivo da recusa da retentativa por contrato (`ENDORSEMENT_RETRY_LIMIT_EXCEEDED`, `ENDORSEMENT_NOT_RETRYABLE`, `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD`) | `error.code` e `error.originalErrors[]`             |
| `CONTRACT_FORMALIZATION_FAILED`       | `null`                                                                                                                                                                                                                                                                                                  | `error.message` e `error.originalErrors[]`          |
| `CONTRACT_DOCUMENT_GENERATION_FAILED` | `null`                                                                                                                                                                                                                                                                                                  | `error.message`                                     |
| `CONTRACT_PAYMENT_FAILED`             | Código do banco liquidante                                                                                                                                                                                                                                                                              | `error.code` e `error.message`; `reason` vem `null` |

A estrutura do `data` dos eventos `CONTRACT_*` está em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

***

## Exemplo de ProblemDetail (erro de borda)

```json
{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 1 second.",
  "errorCode": "INGRESS_RATE_LIMIT_EXCEEDED",
  "timestamp": "2026-06-14T12:00:00Z"
}
```

***

## Erro de operação (OperationError) <a href="#operationerror" id="operationerror"></a>

{% hint style="warning" %}
O `OperationError` **não é um `ProblemDetail`** e **não tem `errorCode`/`status`/`type`**. Ele descreve o desfecho de uma **operação FGTS** — não uma falha da requisição HTTP. Aparece em dois lugares:

* no campo `error` da resposta de polling (`GET /api/v1/fgts/operations/{requestId}`). Vem preenchido em `FAILED`, `FAILED_NEEDS_MANUAL` e `EXPIRED`, e **também** em `NEEDS_VERIFICATION`, onde descreve a verificação em curso e não um desfecho. Em `QUEUED`, `COMPLETED` e `CANCELLED` vem `null`;
* no campo `data.error` do [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md), nos eventos de falha, expiração e cancelamento.
  {% endhint %}

### Estrutura

| Campo               | Tipo                | Descrição                                                                                                                                                                                                                                                                                                                       |
| ------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`              | `string`            | Código de erro **canônico GTLab** estável para uso programático. Ex.: `ENDORSEMENT_DENIED`, `PROVIDER_ERROR`, `OPERATION_NOT_YET_ALLOWED`. É o código **mapeado** — não o código cru da Caixa. A lista completa está no [Catálogo de códigos](#catalogo-operacao).                                                              |
| `message`           | `string`            | Mensagem legível descrevendo o erro. Texto de apresentação: não faça parse.                                                                                                                                                                                                                                                     |
| `originalErrors[]`  | `array`             | Erros **crus** do provedor (Caixa). Presente **apenas quando houve chamada à Caixa com erro** — ausente em erros de lógica interna (ex.: validação, recusa de gate). É uma lista para suportar operações multi-reserva (um erro por item).                                                                                      |
| `originalRequestId` | `string` (opcional) | Presente **apenas** no polling, quando `code` ∈ {`ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE`, `GUARANTEE_APPROVAL_ALREADY_PENDING`}: o `requestId` da operação que de fato está em andamento (ou concluída). Consulte-o para acompanhar o desfecho real. Ver [Recusas de duplicidade](#originalrequestid). |

Cada item de `originalErrors[]`:

| Campo               | Tipo                 | Descrição                                                                                                                                                                |
| ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `provider`          | `string`             | Provedor que gerou o erro — sempre `CAIXA`.                                                                                                                              |
| `code`              | `string`             | **Código cru da Caixa** (não mapeado), ex.: `"37"`. Ver [Códigos da Caixa](#catalogo-caixa). Ausente quando a Caixa respondeu sem código (ex.: falha da borda da Caixa). |
| `description`       | `string`             | Descrição textual do erro retornada pela Caixa.                                                                                                                          |
| `httpStatus`        | `integer`            | HTTP status retornado pelo provedor na chamada original (ex.: `400`).                                                                                                    |
| `requestIdentifier` | `string`             | Identificador de rastreio da solicitação no provedor. Em multi-reserva, atribui o erro ao item específico.                                                               |
| `occurredAt`        | `string` (date-time) | Instante em que o erro ocorreu no provedor (ISO-8601 UTC).                                                                                                               |

{% hint style="info" %}
Os **códigos crus da Caixa** vivem em `originalErrors[].code` — **não** em `code` (que é o código GTLab mapeado). O mesmo código cru pode virar códigos GTLab diferentes conforme a operação: o `7` é retentado automaticamente na averbação e vira `CPF_NOT_OPERABLE` na consulta de saldo. A tabela por operação está em [Códigos da Caixa](#catalogo-caixa).
{% endhint %}

### Recusa por data: `OPERATION_NOT_YET_ALLOWED` <a href="#operation-not-yet-allowed" id="operation-not-yet-allowed"></a>

A Caixa recusa algumas operações **apenas até uma data**, e informa a data na própria resposta: *"Operação não permitida antes de 02/09/2026."* Nesses casos o `error.code` é **`OPERATION_NOT_YET_ALLOWED`** — não `ENDORSEMENT_DENIED` nem `CPF_NOT_OPERABLE`.

A distinção importa para quem decide o que fazer depois:

| `code`                      | O que aconteceu                                                                                                        | O que fazer                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `OPERATION_NOT_YET_ALLOWED` | Nada está errado com o CPF nem com a requisição. Existe uma janela: a mesma operação passa a partir da data informada. | Reenviar **a partir da data**. Reenviar antes repete a mesma recusa.                       |
| `CPF_NOT_OPERABLE`          | Impedimento na conta de FGTS do trabalhador (ex.: mudanças cadastrais, autorização pendente).                          | Só o trabalhador resolve — no app do FGTS ou junto à Caixa. Reenviar sem isso não adianta. |
| `ENDORSEMENT_DENIED`        | A Caixa avaliou e negou no mérito (ex.: saldo insuficiente, código `37`).                                              | Não reenviar sem que a causa mude.                                                         |

Ocorre na **consulta de saldo**, na **averbação**, no **cancelamento de reserva** e na **manutenção de garantia** (códigos crus `10` e `25`).

**A data vem no texto, não em campo próprio.** Ela aparece em `error.message` e em `originalErrors[].description`. Como todo texto de apresentação, não é contrato: **não faça parse dele em produção** — use-o para exibir ao operador, e programe pelo `error.code`.

```json
{
  "code": "OPERATION_NOT_YET_ALLOWED",
  "message": "10: Operação não permitida antes de 02/09/2026.",
  "originalErrors": [
    {
      "provider": "CAIXA",
      "code": "10",
      "description": "Operação não permitida antes de 02/09/2026.",
      "httpStatus": 400,
      "occurredAt": "2026-08-19T12:00:03Z"
    }
  ]
}
```

### Recusas de duplicidade e `originalRequestId` <a href="#originalrequestid" id="originalrequestid"></a>

Uma operação **recusada na admissão do processamento** (averbação duplicada, recusa no gate de cancelamento/manutenção) **não gera `404`** no polling: responde `200` com `status = FAILED` já na primeira consulta, com o **mesmo `error.code`** do evento `FAILED` entregue por webhook. Nas recusas de **duplicidade**, o `error` traz também `originalRequestId` — o `requestId` da operação original, para você acompanhar o desfecho real:

| `code`                               | Quando ocorre                                                                                                                                       | `originalRequestId`                                                           |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `ENDORSEMENT_ALREADY_SUBMITTED`      | A averbação submetida já foi enviada antes para a mesma reserva.                                                                                    | O `requestId` da submissão que de fato virou (ou está virando) a garantia.    |
| `GUARANTEE_OPERATION_DUPLICATE`      | A submissão foi absorvida por uma operação já em andamento com a mesma `Idempotency-Key`.                                                           | O `requestId` original — o resultado sai nele, não no novo.                   |
| `GUARANTEE_APPROVAL_ALREADY_PENDING` | Já existe uma operação desta garantia aguardando **aprovação manual**.                                                                              | O `requestId` da operação pendente de aprovação.                              |
| `DUPLICATE_RESERVE_IDENTIFIER`       | Duas averbações simultâneas com o mesmo `reserveIdentifier`; a segunda é recusada antes de chegar à Caixa. Chega pelo webhook `ENDORSEMENT_FAILED`. | Não vem. Acompanhe a averbação original. Esta recusa não consome retentativa. |

Programe sempre pelo `error.code`: o `error.message` é texto de apresentação e pode mudar sem aviso.

```json
{
  "code": "ENDORSEMENT_ALREADY_SUBMITTED",
  "message": "Averbação já submetida para esta reserva",
  "originalRequestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
```

### Exemplo de OperationError (no `error` do polling)

```json
{
  "code": "ENDORSEMENT_DENIED",
  "message": "Averbação negada pelo provedor Caixa",
  "originalErrors": [
    {
      "provider": "CAIXA",
      "code": "37",
      "description": "Trabalhador não possui saldo suficiente para a garantia",
      "httpStatus": 400,
      "requestIdentifier": "RES-20240901-001",
      "occurredAt": "2026-06-14T12:00:03Z"
    }
  ]
}
```

Como esse erro se encaixa no ciclo de vida da operação está em [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md). O mesmo `OperationError` entregue por webhook está em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).

***

## Catálogo de códigos <a href="#catalogo" id="catalogo"></a>

Todos os códigos que a API pode devolver, agrupados por onde aparecem. Coluna **Repetir?**:

* **Sim** — repita a mesma requisição depois de esperar.
* **Após corrigir** — corrija algo antes de repetir.
* **Não** — não repita; o resultado não muda.
* **Automático** — a plataforma já está repetindo; apenas aguarde.

### Erros de borda (resposta HTTP) <a href="#catalogo-borda" id="catalogo-borda"></a>

#### Validação e acesso

| `errorCode`                      | HTTP               | Rotas                                     | Quando ocorre                                                                                                                                                                     | Repetir?      | O que fazer                                               |
| -------------------------------- | ------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------- |
| `VALIDATION_ERROR`               | 400                | Todas                                     | Campo, parâmetro de URL ou header fora do padrão; JSON malformado; `Idempotency-Key` ausente; PDF inválido em `signedDocumentBase64`. Ver [Erro de Validação](#validation-error). | Após corrigir | Corrigir os campos em `errors` (ou o motivo em `detail`). |
| *(sem `errorCode`)*              | 404, 405, 406, 415 | Todas                                     | Rota inexistente, método não suportado, `Accept` incompatível, `Content-Type` diferente de `application/json`.                                                                    | Após corrigir | Tratar pelo status HTTP.                                  |
| `UNAUTHORIZED`                   | 401                | Todas                                     | Token ausente, inválido, expirado ou revogado.                                                                                                                                    | Após corrigir | Renovar o token.                                          |
| `ORIGINATOR_OWNERSHIP_VIOLATION` | 403                | `GET /api/v1/fgts/operations/{requestId}` | `requestId` de outro originator.                                                                                                                                                  | Não           | Consultar só `requestId` próprios.                        |

#### Operações FGTS

| `errorCode`                                   | HTTP | Rotas                                                                                                                                                                                                      | Quando ocorre                                                                                                                     | Repetir?      | O que fazer                                                                                                                                                                               |
| --------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPERATION_NOT_FOUND`                         | 404  | `GET` e `DELETE /api/v1/fgts/operations/{requestId}`                                                                                                                                                       | `requestId` desconhecido, ou consultado segundos depois do `202`.                                                                 | Após corrigir | Conferir o id; se acabou de submeter, consultar de novo em seguida.                                                                                                                       |
| `OPERATION_NOT_CANCELLABLE`                   | 409  | `DELETE /api/v1/fgts/operations/{requestId}`                                                                                                                                                               | A operação já saiu de `QUEUED`, ou é averbação, manutenção de garantia ou cancelamento de reserva (não canceláveis pelo cliente). | Não           | Acompanhar o desfecho pelo polling. Para desfazer uma averbação, submeter cancelamento de reserva ou cancelar o contrato.                                                                 |
| `ORIGINATOR_CODE_NOT_ASSIGNED`                | 422  | `POST /api/v1/fgts/endorsements`                                                                                                                                                                           | Originator sem código cadastrado; o `reserveIdentifier` não pode ser gerado.                                                      | Não           | Acionar a Giro.                                                                                                                                                                           |
| `IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`            | 422  | Todas as submissões de operação FGTS, a retentativa por identificador e as rotas de contrato `.../reserve-cancellations`, `.../guarantee-maintenances`, `.../endorsement-retries` e `.../payment-approval` | A `Idempotency-Key` já foi usada nesta rota com outro corpo ou outro identificador na URL. Nada é enfileirado.                    | Após corrigir | Chave nova para operação nova; para reenviar a original, o corpo idêntico. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md#payload-diferente). |
| `GUARANTEE_NOT_FOUND`                         | 404  | `POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`                                                                                                                                               | `reserveIdentifier` desconhecido ou de outro originator.                                                                          | Não           | Conferir o identificador.                                                                                                                                                                 |
| `ENDORSEMENT_RETRY_LIMIT_EXCEEDED`            | 409  | idem                                                                                                                                                                                                       | Teto de 3 retentativas atingido.                                                                                                  | Não           | Nova averbação, ou suporte.                                                                                                                                                               |
| `ENDORSEMENT_NOT_RETRYABLE`                   | 409  | idem                                                                                                                                                                                                       | A reserva não está em falha retentável — inclusive durante a [retentativa automática](#retrying).                                 | Após corrigir | Aguardar o desfecho em curso.                                                                                                                                                             |
| `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` | 409  | idem                                                                                                                                                                                                       | Reserva em formato anterior ao atual.                                                                                             | Não           | Submeter averbação nova.                                                                                                                                                                  |
| `GUARANTEE_LEDGER_CLIENT_ERROR`               | 4xx  | idem, e `GET /api/v1/fgts/operations/{requestId}`                                                                                                                                                          | A plataforma não conseguiu concluir a requisição. Um `401`/`403` aqui não se refere ao seu token.                                 | Não           | Acionar o suporte com o `requestId`.                                                                                                                                                      |

#### Contratos <a href="#catalogo-contrato" id="catalogo-contrato"></a>

| `errorCode`                                                                                                | HTTP | Rotas                                                                                                | Quando ocorre                                                                                        | Repetir?      | O que fazer                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTRACT_DOCUMENT_REQUIRED`                                                                               | 400  | `POST /contracts`                                                                                    | `generateDocument=false` sem `signedDocumentBase64`.                                                 | Após corrigir | Enviar o PDF, ou usar `generateDocument=true`.                                                                                                |
| `CONTRACT_DOCUMENT_UNEXPECTED`                                                                             | 400  | `POST /contracts`                                                                                    | `generateDocument=true` com `signedDocumentBase64` preenchido.                                       | Após corrigir | Escolher um dos modos.                                                                                                                        |
| `CONTRACT_FIRST_DUE_DATE_MISMATCH`                                                                         | 400  | `POST /contracts`                                                                                    | `financialTerms.firstDueDate` diferente da primeira parcela.                                         | Após corrigir | Igualar as datas.                                                                                                                             |
| `CONTRACT_INSTALLMENTS_MISMATCH`                                                                           | 400  | `POST /contracts`                                                                                    | `installmentCount` diferente do número de parcelas enviadas.                                         | Após corrigir | Alinhar a contagem.                                                                                                                           |
| `CCB_VALIDATION_FAILED`                                                                                    | 400  | `POST /contracts`                                                                                    | A validação prévia da CCB recusou os dados.                                                          | Após corrigir | Corrigir os campos em `errors`.                                                                                                               |
| `PAYMENT_PROOF_UNSUPPORTED_CONTENT_TYPE`                                                                   | 400  | `POST .../reserve-cancellations`                                                                     | `paymentProof.contentType` fora de `application/pdf`, `image/png`, `image/jpeg`.                     | Após corrigir | Enviar PDF, PNG ou JPEG com o tipo correspondente.                                                                                            |
| `PAYMENT_PROOF_INVALID_BASE64`                                                                             | 400  | `POST .../reserve-cancellations`                                                                     | `paymentProof.contentBase64` não é Base64 válido.                                                    | Após corrigir | Codificar o arquivo em Base64 padrão.                                                                                                         |
| `PAYMENT_PROOF_CONTENT_MISMATCH`                                                                           | 400  | `POST .../reserve-cancellations`                                                                     | O conteúdo não é do tipo declarado em `contentType`.                                                 | Após corrigir | Ajustar o `contentType` ao arquivo real.                                                                                                      |
| `PAYMENT_PROOF_TOO_LARGE`                                                                                  | 413  | `POST .../reserve-cancellations`                                                                     | Comprovante acima de 5 MiB decodificado.                                                             | Após corrigir | Reduzir o arquivo (ex.: PDF em vez de foto).                                                                                                  |
| `PAYLOAD_TOO_LARGE`                                                                                        | 413  | Todas as rotas com corpo JSON                                                                        | Corpo acima de 15 MiB.                                                                               | Após corrigir | Reduzir o corpo (no comprovante e no PDF da CCB, o arquivo).                                                                                  |
| `CONTRACT_NOT_FOUND`                                                                                       | 404  | Todas as rotas `/contracts/{contractNumber}/**`                                                      | Contrato inexistente ou de outro originator.                                                         | Não           | Conferir o `contractNumber`.                                                                                                                  |
| `CONTRACT_DOCUMENT_NOT_AVAILABLE`                                                                          | 404  | `GET .../documents/template`                                                                         | CCB ainda não gerada, ou contrato em `DOCUMENT_GENERATION_FAILED`.                                   | Sim           | Aguardar `CONTRACT_DOCUMENT_GENERATED` — que pode chegar mesmo depois de `CONTRACT_DOCUMENT_GENERATION_FAILED`; se a geração falhou, suporte. |
| `CONTRACT_SIGNED_DOCUMENT_NOT_AVAILABLE`                                                                   | 404  | `GET .../documents/signed`                                                                           | PDF assinado ainda não anexado.                                                                      | Sim           | Consultar depois do anexo.                                                                                                                    |
| `CONTRACT_IDEMPOTENCY_CONFLICT`                                                                            | 409  | `POST /contracts`, `POST .../documents`                                                              | Mesma `Idempotency-Key` com payload diferente; documento enviado fora de `AWAITING_SIGNED_DOCUMENT`. | Após corrigir | Nova chave se o payload mudou; no envio de documento, consultar o contrato.                                                                   |
| `CONTRACT_NOT_CANCELLABLE`                                                                                 | 409  | `DELETE /contracts/{contractNumber}`                                                                 | Contrato pago ou terminal.                                                                           | Não           | Consultar o contrato.                                                                                                                         |
| `CONTRACT_ALREADY_DISBURSED`                                                                               | 409  | `DELETE /contracts/{contractNumber}`                                                                 | Um cancelamento anterior foi interrompido porque o provedor já pagou a CCB.                          | Não           | Enviar a desistência (`SEVEN_DAYS_REGRET`) em `reserve-cancellations`.                                                                        |
| `CONTRACT_NOT_PENDING_PAYMENT_APPROVAL`                                                                    | 409  | `POST .../payment-approval`                                                                          | Contrato fora de `PENDING_PAYMENT_APPROVAL`.                                                         | Não           | Consultar o contrato.                                                                                                                         |
| `CONTRACT_NOT_IN_REVISION`                                                                                 | 409  | `PUT .../disbursement-account`                                                                       | Sem revisão de desembolso aberta, ou prazo vencido.                                                  | Não           | Trocar a conta só com `revision` aberta.                                                                                                      |
| `ACCOUNT_AMENDMENT_IN_FLIGHT`                                                                              | 409  | `PUT .../disbursement-account`                                                                       | Ajuste anterior ainda em curso.                                                                      | Sim           | Aguardar o desfecho do ajuste anterior.                                                                                                       |
| `CONTRACT_INVALID_STATUS`                                                                                  | 409  | `POST .../endorsement-retries`                                                                       | Contrato fora de `ENDORSEMENT_REJECTED`.                                                             | Não           | Retentar só averbação recusada.                                                                                                               |
| `CONTRACT_NO_ACTIVE_RESERVATION`                                                                           | 409  | `POST .../reserve-cancellations`, `POST .../guarantee-maintenances`                                  | Contrato sem reserva ativa.                                                                          | Não           | Consultar o contrato.                                                                                                                         |
| `CONTRACT_CLIENT_REFERENCE_ALREADY_EXISTS`                                                                 | 422  | `POST /contracts`                                                                                    | `clientReference` já usado.                                                                          | Não           | Usar referência única, ou consultar o contrato existente.                                                                                     |
| `CONTRACT_NUMBER_ALREADY_EXISTS`                                                                           | 422  | `POST /contracts`                                                                                    | `contractNumber` já existe para o originator.                                                        | Após corrigir | Informar outro número, ou omitir.                                                                                                             |
| `CONTRACT_NUMBER_ALLOCATION_EXHAUSTED`                                                                     | 422  | `POST /contracts`                                                                                    | Sem número livre para gerar.                                                                         | Não           | Acionar o suporte.                                                                                                                            |
| `FORMALIZATION_CONFIG_NOT_PROVISIONED`, `FORMALIZATION_CONFIG_INCOMPLETE`, `GTBANKER_CREDENTIAL_NOT_FOUND` | 422  | `POST /contracts`                                                                                    | Originator ainda não configurado para formalizar.                                                    | Não           | Acionar a Giro.                                                                                                                               |
| `DISBURSEMENT_ACCOUNT_REJECTED`                                                                            | 422  | `PUT .../disbursement-account`                                                                       | O banco recusou a conta nova.                                                                        | Após corrigir | Informar outra conta ou chave PIX.                                                                                                            |
| `CONTRACT_REQUEST_REJECTED`                                                                                | 4xx  | Todas as rotas `/contracts/**`                                                                       | O serviço de formalização recusou sem código próprio.                                                | Após corrigir | Ler `detail` e `errors`; sem `errors`, suporte.                                                                                               |
| `RATE_LIMIT_EXCEEDED`                                                                                      | 429  | `POST /contracts`, `POST .../documents`, `PUT .../disbursement-account`, `POST .../payment-approval` | Mais de 30 req/min.                                                                                  | Sim           | Aguardar `Retry-After`.                                                                                                                       |

#### Simulações e webhook

| `errorCode`                                                                                                                                              | HTTP | Rotas                                    | Quando ocorre                                                                                                                                        | Repetir?      | O que fazer                     |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------- |
| `SIMULATION_REJECTED`, `INSTALLMENT_AMOUNT_BELOW_MINIMUM`, `INSTALLMENT_AMOUNT_ABOVE_MAXIMUM`, `MAX_INSTALLMENT_YEARS_EXCEEDED`, `INVALID_TRANSFER_DATE` | 400  | `POST /api/v1/simulations`               | Regra de produto da simulação. Ver [Criar Simulação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/simulacoes/criar-simulacao.md). | Após corrigir | Ajustar taxa, datas ou valores. |
| `CET_NOT_CONVERGED`, `CET_ABOVE_MAXIMUM`                                                                                                                 | 422  | `POST /api/v1/simulations`               | CET não calculável, ou acima de 9999,999999% ao ano.                                                                                                 | Após corrigir | Ajustar custos e prazos.        |
| `SIMULATION_NOT_FOUND`                                                                                                                                   | 404  | `GET /api/v1/simulations/{simulationId}` | Inexistente ou de outro originator.                                                                                                                  | Não           | Conferir o id.                  |
| `WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS`                                                                                                                    | 409  | `POST /api/v1/webhooks`                  | Já existe cadastro.                                                                                                                                  | Não           | Usar `PUT`.                     |
| `WEBHOOK_SUBSCRIPTION_NOT_FOUND`                                                                                                                         | 404  | `GET`, `PUT`, `DELETE /api/v1/webhooks`  | Sem cadastro.                                                                                                                                        | Não           | Usar `POST`.                    |
| `CONFLICT`                                                                                                                                               | 409  | `POST /api/v1/webhooks`                  | Dois cadastros simultâneos.                                                                                                                          | Não           | Consultar o cadastro.           |
| `RATE_LIMIT_EXCEEDED`                                                                                                                                    | 429  | `POST /api/v1/webhooks`                  | Mais de 25 req/min.                                                                                                                                  | Sim           | Aguardar `Retry-After`.         |

#### Limite e indisponibilidade

| `errorCode`                          | HTTP | Rotas                                                                        | Quando ocorre                                   | Repetir? | O que fazer                                                  |
| ------------------------------------ | ---- | ---------------------------------------------------------------------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------ |
| `INGRESS_RATE_LIMIT_EXCEEDED`        | 429  | Submissões de operação FGTS                                                  | Teto de vazão do originator.                    | Sim      | Aguardar `Retry-After` (1 s) e reduzir a taxa.               |
| `SUBMISSION_TEMPORARILY_UNAVAILABLE` | 503  | Submissões FGTS, contratos e, em indisponibilidade momentânea, qualquer rota | Indisponibilidade momentânea; nada foi gravado. | Sim      | Repetir após `Retry-After` (5 s), mesmo corpo e mesma chave. |
| `DISPATCHER_UNAVAILABLE`             | 503  | `GET` e `DELETE /api/v1/fgts/operations/{requestId}`                         | Consulta de operação indisponível.              | Sim      | Repetir após `Retry-After` (30 s).                           |
| `GUARANTEE_LEDGER_UNAVAILABLE`       | 503  | Retentativa por identificador; `GET /api/v1/fgts/operations/{requestId}`     | Indisponibilidade temporária.                   | Sim      | Repetir após `Retry-After`.                                  |
| `UPSTREAM_UNAVAILABLE`               | 503  | Simulações                                                                   | Simulador indisponível; **sem** `Retry-After`.  | Sim      | Backoff próprio.                                             |
| `CAIXA_MAINTENANCE_WINDOW`           | 503  | `POST /api/v1/fgts/balance-queries`                                          | Manutenção programada da Caixa.                 | Sim      | Repetir após `maintenanceEndsAt`, ou usar o lote.            |
| `INTERNAL_ERROR`                     | 500  | Todas                                                                        | Erro inesperado.                                | Sim      | Repetir uma vez com a mesma chave; depois, suporte.          |

### Status da operação (polling) <a href="#catalogo-status" id="catalogo-status"></a>

Valores de `status` em `GET /api/v1/fgts/operations/{requestId}`:

| `status`                  | Significado                                                                                                | `error`                                                         | O que fazer                                                                                                                           |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `QUEUED`                  | Na fila.                                                                                                   | `null`                                                          | Aguardar.                                                                                                                             |
| `DISPATCHING`             | Sendo despachada — ou, num cancelamento ou manutenção, aprovada na revisão manual e ainda não executada.   | `null`                                                          | Aguardar.                                                                                                                             |
| `IN_FLIGHT`               | Chamada à Caixa em andamento.                                                                              | `null`                                                          | Aguardar.                                                                                                                             |
| `AWAITING_PROVIDER`       | Averbação aceita pela Caixa e ainda em processamento do lado dela; a plataforma reconsulta periodicamente. | `null`                                                          | Aguardar. **Não** reenviar.                                                                                                           |
| `RETRYING`                | Em [retentativa automática](#retrying) após falha transitória da Caixa.                                    | O motivo da espera está em `retry.lastProviderError`.           | Aguardar. **Não** reenviar. Se `retry.lastProviderError.code` for `7`, peça ao trabalhador que autorize a instituição no app do FGTS. |
| `NEEDS_VERIFICATION`      | Resultado ambíguo (ex.: timeout); a plataforma está confirmando junto à Caixa se a operação foi gravada.   | Preenchido com `<OPERAÇÃO>_NEEDS_VERIFICATION`. Não é desfecho. | Aguardar. **Não** reenviar.                                                                                                           |
| `PENDING_MANUAL_APPROVAL` | Cancelamento de reserva ou manutenção de garantia aguardando revisão manual da Giro.                       | `null`                                                          | Aguardar.                                                                                                                             |
| `COMPLETED`               | Sucesso.                                                                                                   | `null`                                                          | Ler `result`.                                                                                                                         |
| `FAILED`                  | Falha terminal.                                                                                            | Preenchido.                                                     | Decidir pelo [`error.code`](#catalogo-operacao).                                                                                      |
| `FAILED_NEEDS_MANUAL`     | O desfecho exige análise humana. **Não gera webhook.**                                                     | Preenchido.                                                     | Acionar o suporte com o `requestId`. Não reenviar.                                                                                    |
| `EXPIRED`                 | Expirou na fila sem ser processada (`error.code = EXPIRED_TTL`).                                           | Preenchido.                                                     | Submeter de novo.                                                                                                                     |
| `CANCELLED`               | Cancelada em `QUEUED`, por você (`DELETE`) ou pela Giro.                                                   | `null`                                                          | Submeter de novo, se ainda precisar.                                                                                                  |

#### Retentativa automática (`RETRYING`) <a href="#retrying" id="retrying"></a>

Na **averbação**, no **cancelamento de reserva** e na **manutenção de garantia**, os códigos crus `3`, `7`, `14` e `524` da Caixa e as falhas da borda da Caixa sem código não encerram a operação: ela entra em `RETRYING` e a plataforma repete sozinha, mantendo o mesmo `reserveIdentifier`, por até **72 horas**. O intervalo cresce com o tempo: **15 minutos** nas 3 primeiras horas, **30 minutos** até 24 horas e **2 horas** daí até o fim da janela. O bloco `retry` do polling traz `providerAttempt`, `nextAttemptAt`, `windowExpiresAt` e `lastProviderError`.

Se a janela se esgota sem sucesso, a operação termina `FAILED` com `error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED`. A partir daí a [retentativa manual](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) fica liberada. Antes disso, ela responde `409 ENDORSEMENT_NOT_RETRYABLE`.

### `error.code` de operação <a href="#catalogo-operacao" id="catalogo-operacao"></a>

Valores de `error.code` no polling e no `data.error` dos webhooks `*_FAILED`, `*_EXPIRED` e `*_CANCELLED`. O código cru da Caixa, quando houver, está em `error.originalErrors[].code` — ver [Códigos da Caixa](#catalogo-caixa).

#### Recusa da Caixa

| `error.code`                | Operações                                                  | Quando ocorre                                                                                       | Repetir?      | O que fazer                                                                                             |
| --------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| `ENDORSEMENT_DENIED`        | Averbação, cancelamento de reserva, manutenção de garantia | A Caixa negou no mérito. O motivo está em `originalErrors[0]`.                                      | Após corrigir | Ler o código cru e corrigir a causa.                                                                    |
| `CANCELLATION_DENIED`       | Cancelamento de reserva                                    | A Caixa indeferiu o pedido de cancelamento.                                                         | Após corrigir | A reserva pode continuar ativa; acione o suporte.                                                       |
| `MAINTENANCE_DENIED`        | Manutenção de garantia                                     | A Caixa indeferiu a manutenção.                                                                     | Após corrigir | Revisar períodos e valores.                                                                             |
| `OPERATION_NOT_YET_ALLOWED` | Todas                                                      | A Caixa só aceita a operação a partir de uma data (códigos crus `10` e `25`).                       | Após corrigir | Reenviar a partir da data. Ver [Recusa por data](#operation-not-yet-allowed).                           |
| `CPF_NOT_OPERABLE`          | Consulta de saldo e demais consultas                       | Impedimento na conta FGTS do trabalhador (códigos crus `5`, `7`, `8`, `9`, `11`, `13`, `18`, `35`). | Após corrigir | Código `7`: o trabalhador autoriza a instituição no app do FGTS. Demais: o trabalhador procura a Caixa. |
| `PROVIDER_ERROR`            | Todas                                                      | Código da Caixa sem mapeamento específico, ou erro sem código. **É terminal, apesar do nome.**      | Após corrigir | Ler `originalErrors`; não repetir igual.                                                                |

#### Indisponibilidade e verificação

| `error.code`                                                                                                   | Operações                           | Quando ocorre                                                                                                           | Repetir?      | O que fazer                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROVIDER_UNAVAILABLE`                                                                                         | Todas                               | Caixa indisponível ou recusando a autenticação da plataforma. Nas consultas, também os códigos crus `3`, `524` e `525`. | Sim           | Submeter de novo mais tarde.                                                                                                                                                             |
| `TRANSIENT_PROVIDER_EDGE_UNAVAILABLE`                                                                          | Consultas                           | A borda da Caixa falhou sem devolver código.                                                                            | Sim           | Submeter de novo.                                                                                                                                                                        |
| `PROVIDER_UNCONFIRMED`                                                                                         | Averbação, cancelamento, manutenção | Timeout na Caixa, e a verificação confirmou que nada foi gravado.                                                       | Sim           | Repetir. Na averbação, pela [retentativa](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) — conta no teto de 3. |
| `TRANSIENT_PROVIDER_RETRY_EXHAUSTED`                                                                           | Averbação, cancelamento, manutenção | A [retentativa automática](#retrying) de 72 h terminou sem sucesso. `originalErrors` vem vazio.                         | Sim           | Retentativa manual liberada. Se o motivo era o código `7`, confirme a autorização do trabalhador antes.                                                                                  |
| `TRANSIENT_VERIFICATION_WINDOW_EXHAUSTED`                                                                      | Averbação, cancelamento, manutenção | A verificação de um resultado ambíguo terminou sem resposta conclusiva.                                                 | Após corrigir | Confirmar a situação da reserva com o suporte antes de repetir.                                                                                                                          |
| `ENDORSEMENT_NEEDS_VERIFICATION`, `CANCEL_RESERVE_NEEDS_VERIFICATION`, `MAINTAIN_GUARANTEE_NEEDS_VERIFICATION` | A respectiva operação               | Aparece em `NEEDS_VERIFICATION` e `FAILED_NEEDS_MANUAL`: verificação em curso ou pendente de análise.                   | Não           | Aguardar o desfecho.                                                                                                                                                                     |
| `UNKNOWN_PROTOCOL_STATUS`                                                                                      | Averbação                           | A Caixa devolveu um status de protocolo desconhecido; a operação fica em `FAILED_NEEDS_MANUAL`.                         | Não           | Aguardar a Giro.                                                                                                                                                                         |
| `DISPATCHER_INTERNAL_ERROR`                                                                                    | Averbação, cancelamento, manutenção | Falha interna da plataforma; a operação fica em `FAILED_NEEDS_MANUAL`, sem webhook.                                     | Não           | Não reenviar; acionar o suporte com o `requestId`.                                                                                                                                       |
| `RETRY_INVALID_PAYLOAD`                                                                                        | Retentativa de averbação            | Não foi possível reprocessar a averbação original; fica em `FAILED_NEEDS_MANUAL`.                                       | Não           | Acionar o suporte.                                                                                                                                                                       |
| `TRANSIENT_NEEDS_MANUAL_EXPIRED`                                                                               | Todas                               | A operação ficou 7 dias em `FAILED_NEEDS_MANUAL` sem resolução e foi encerrada.                                         | Após corrigir | Confirmar a situação com o suporte e submeter de novo.                                                                                                                                   |
| `TRANSIENT_MANUAL_DISCARD`                                                                                     | Averbação, cancelamento, manutenção | A Giro encerrou a operação após análise. Não é negativa da Caixa.                                                       | Após corrigir | Confirmar a situação da reserva com o suporte.                                                                                                                                           |
| `EXPIRED_TTL`                                                                                                  | Todas                               | A operação expirou na fila (`status = EXPIRED`).                                                                        | Sim           | Submeter de novo.                                                                                                                                                                        |
| `PROVIDER_RETRY_WINDOW`                                                                                        | Averbação, cancelamento, manutenção | Marcador de evento `*_RETRYING`. Não é falha.                                                                           | Automático    | Não tratar como erro.                                                                                                                                                                    |

#### Recusa antes da Caixa

| `error.code`                                                                                                                           | Operações                                                                            | Quando ocorre                                                                                                                                                                                                                                                                                | Repetir?      | O que fazer                                   |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------- |
| `RESERVE_NOT_FOUND`                                                                                                                    | Consulta de valor reservado, consulta de protocolos por reserva                      | O `reserveIdentifier` não pertence ao originator. A Caixa não é chamada.                                                                                                                                                                                                                     | Após corrigir | Conferir o identificador.                     |
| `ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE`, `GUARANTEE_APPROVAL_ALREADY_PENDING`, `DUPLICATE_RESERVE_IDENTIFIER` | Averbação, cancelamento, manutenção                                                  | Duplicidade. Ver [Recusas de duplicidade](#originalrequestid).                                                                                                                                                                                                                               | Não           | Acompanhar a operação original.               |
| `GUARANTEE_APPROVAL_REJECTED`                                                                                                          | Cancelamento de reserva, manutenção de garantia                                      | Reprovada na revisão manual da Giro. O `status` é `FAILED`.                                                                                                                                                                                                                                  | Não           | Alinhar com a Giro antes de submeter de novo. |
| `CONTRACT_ALREADY_DISBURSED`                                                                                                           | Cancelamento de reserva, cancelamento de contrato (`CONTRACT_CANCELLATION_REJECTED`) | A CCB estava no provedor sem desembolso e a operação da Giro confirmou que ela já foi paga. Mensagem: "O contrato já foi desembolsado pelo GTBanker e o cancelamento foi interrompido. Para desfazer a operação, envie um cancelamento de reserva com cancellationType SEVEN\_DAYS\_REGRET." | Não           | Enviar a desistência (`SEVEN_DAYS_REGRET`).   |
| `GUARANTEE_NOT_FOUND`                                                                                                                  | idem                                                                                 | Nenhuma garantia corresponde aos dados informados.                                                                                                                                                                                                                                           | Após corrigir | Conferir os dados.                            |
| `GUARANTEE_NOT_GATEABLE`                                                                                                               | idem                                                                                 | A garantia não está averbada nem amortizada.                                                                                                                                                                                                                                                 | Não           | Consultar o contrato.                         |
| `GUARANTEE_ALREADY_CANCELLED`                                                                                                          | idem                                                                                 | A garantia já foi cancelada.                                                                                                                                                                                                                                                                 | Não           | Nada a fazer.                                 |
| `INSTALLMENT_NOT_FOUND`                                                                                                                | Manutenção de garantia                                                               | Não há parcela em aberto para o `transferDate` informado.                                                                                                                                                                                                                                    | Após corrigir | Corrigir a data.                              |
| `ADJUSTMENT_EXCEEDS_RESIDUAL_AMOUNT`                                                                                                   | Manutenção de garantia                                                               | `amount` maior que o saldo residual da parcela.                                                                                                                                                                                                                                              | Após corrigir | Reduzir o valor.                              |
| `GUARANTEE_OPERATION_REFUSED`                                                                                                          | Cancelamento de reserva, manutenção de garantia                                      | Recusa sem motivo específico.                                                                                                                                                                                                                                                                | Não           | Acionar o suporte.                            |
| `OPERATOR_CANCELLED`                                                                                                                   | Todas                                                                                | A Giro cancelou a operação enquanto estava em `QUEUED` (webhook `*_CANCELLED`). No polling, o `status` é `CANCELLED` com `error` `null`.                                                                                                                                                     | Após corrigir | Submeter de novo, se ainda precisar.          |

### Códigos da Caixa <a href="#catalogo-caixa" id="catalogo-caixa"></a>

O código cru chega em `error.originalErrors[].code` ou em `retry.lastProviderError.code`. A mesma resposta da Caixa vira códigos GTLab diferentes conforme a operação:

* **Escrita** — averbação, cancelamento de reserva e manutenção de garantia.
* **Consulta** — consulta de saldo, consulta de valor reservado, consulta de protocolos por reserva e consulta de status de protocolo.
* **Retentativa automática** — a operação entra em [`RETRYING`](#retrying) e só termina se a janela de 72 h se esgotar.

| Código                          | Descrição da Caixa (resumo)                         | Escrita                                                                                                                                | Consulta                              | O que fazer                                                                                      |
| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `1`                             | Falha de autenticação da plataforma na Caixa        | `PROVIDER_UNAVAILABLE`                                                                                                                 | `PROVIDER_UNAVAILABLE`                | Submeter de novo mais tarde.                                                                     |
| `3`                             | Erro inesperado na Caixa                            | Retentativa automática                                                                                                                 | `PROVIDER_UNAVAILABLE`                | Escrita: aguardar. Consulta: submeter de novo.                                                   |
| `5`                             | Operação fiduciária em andamento para o trabalhador | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | Reenviar quando a outra operação terminar.                                                       |
| `6`                             | Instituição sem convênio                            | `ENDORSEMENT_DENIED`                                                                                                                   | `PROVIDER_ERROR`                      | Acionar o suporte.                                                                               |
| `7`                             | Trabalhador não autorizou a instituição             | Retentativa automática                                                                                                                 | `CPF_NOT_OPERABLE`                    | O trabalhador autoriza a instituição no app do FGTS.                                             |
| `8`                             | Trabalhador sem conta FGTS                          | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | Não reenviar.                                                                                    |
| `9`                             | Trabalhador sem adesão ao saque-aniversário         | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | Reenviar após a adesão.                                                                          |
| `10`                            | Operação não permitida antes de uma data            | `OPERATION_NOT_YET_ALLOWED`                                                                                                            | `OPERATION_NOT_YET_ALLOWED`           | Reenviar a partir da data.                                                                       |
| `11`                            | CPF não operável                                    | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | O trabalhador procura a Caixa.                                                                   |
| `12`                            | Sem saldo disponível                                | `ENDORSEMENT_DENIED`                                                                                                                   | —                                     | Reenviar só após nova consulta de saldo positiva.                                                |
| `13`                            | Pendência no pagamento do saque-aniversário         | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | Reenviar após a regularização.                                                                   |
| `14`                            | Já existe solicitação com o mesmo identificador     | Retentativa automática: a plataforma verifica e adota a solicitação existente                                                          | —                                     | Aguardar.                                                                                        |
| `15`                            | Sem adesão para o período informado                 | `ENDORSEMENT_DENIED`                                                                                                                   | —                                     | Revisar os períodos.                                                                             |
| `16`                            | Datas de previsão não conferem                      | `ENDORSEMENT_DENIED`                                                                                                                   | —                                     | Refazer a consulta de saldo e usar as datas dela.                                                |
| `17`                            | Valor acima do disponível                           | `ENDORSEMENT_DENIED`                                                                                                                   | —                                     | Reduzir o valor.                                                                                 |
| `18`                            | Saque-rescisão pendente                             | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | O trabalhador cancela o pedido na Caixa.                                                         |
| `20`                            | Quitação não deve informar períodos                 | `PROVIDER_ERROR`                                                                                                                       | —                                     | Corrigir o payload.                                                                              |
| `21`                            | Operação não localizada                             | `PROVIDER_ERROR`                                                                                                                       | —                                     | Conferir os dados da reserva.                                                                    |
| `22`                            | Operação cancelada                                  | `PROVIDER_ERROR`                                                                                                                       | —                                     | Não reenviar.                                                                                    |
| `23`                            | Garantia transferida para outra instituição         | `PROVIDER_ERROR`                                                                                                                       | —                                     | Não reenviar; o detalhe vem em `description`.                                                    |
| `24`                            | Manutenção não permitida                            | `PROVIDER_ERROR`                                                                                                                       | —                                     | Não reenviar.                                                                                    |
| `25`                            | Manutenção não permitida antes de uma data          | `OPERATION_NOT_YET_ALLOWED`                                                                                                            | —                                     | Reenviar a partir da data.                                                                       |
| `26`                            | Datas não constam na operação                       | `PROVIDER_ERROR`                                                                                                                       | —                                     | Corrigir `periods[]`.                                                                            |
| `27`                            | Operação já cancelada                               | `PROVIDER_ERROR`                                                                                                                       | —                                     | Tratar a reserva como já cancelada.                                                              |
| `28`                            | Cancelamento não permitido                          | `PROVIDER_ERROR`                                                                                                                       | —                                     | Acionar o suporte.                                                                               |
| `29`                            | Protocolo não encontrado                            | —                                                                                                                                      | `PROVIDER_ERROR`                      | Conferir o número do protocolo.                                                                  |
| `30`                            | Nenhum protocolo encontrado                         | —                                                                                                                                      | `PROVIDER_ERROR`                      | A reserva não tem protocolos; trate como lista vazia.                                            |
| `31`                            | Identificador não localizado                        | —                                                                                                                                      | `PROVIDER_ERROR`                      | Conferir se a averbação foi concluída.                                                           |
| `33`                            | Amortização acima do saldo do exercício             | `PROVIDER_ERROR`                                                                                                                       | —                                     | Reduzir `amount`.                                                                                |
| `35`                            | Mudança cadastral impede a contratação              | `ENDORSEMENT_DENIED`                                                                                                                   | `CPF_NOT_OPERABLE`                    | O trabalhador procura a Caixa.                                                                   |
| `37`                            | Saldo insuficiente para a garantia                  | `ENDORSEMENT_DENIED`                                                                                                                   | —                                     | Reduzir o valor.                                                                                 |
| `38`                            | Identificador da solicitação inválido               | `ENDORSEMENT_DENIED`                                                                                                                   | `PROVIDER_ERROR`                      | Acionar o suporte.                                                                               |
| `40`                            | Faltam dados cadastrais do trabalhador              | `PROVIDER_ERROR`                                                                                                                       | `PROVIDER_ERROR`                      | O trabalhador procura a Caixa.                                                                   |
| `47`                            | Quantidade de exercícios acima do máximo            | `PROVIDER_ERROR`                                                                                                                       | `PROVIDER_ERROR`                      | Reduzir os períodos.                                                                             |
| `48`                            | Valor abaixo do mínimo                              | `PROVIDER_ERROR`                                                                                                                       | —                                     | Aumentar o valor.                                                                                |
| `51`                            | Valor acima do máximo                               | `PROVIDER_ERROR`                                                                                                                       | —                                     | Reduzir o valor.                                                                                 |
| `52`                            | Trabalhador já tem o máximo de reservas             | `ENDORSEMENT_DENIED`; o contrato é cancelado                                                                                           | —                                     | Não reenviar.                                                                                    |
| `524`                           | Timeout da borda da Caixa                           | Retentativa automática                                                                                                                 | `PROVIDER_UNAVAILABLE`                | Escrita: aguardar. Consulta: submeter de novo.                                                   |
| `525`                           | Borda da Caixa indisponível                         | `PROVIDER_ERROR`                                                                                                                       | `PROVIDER_UNAVAILABLE`                | Escrita: consulte os protocolos da reserva antes de reenviar — a operação pode ter sido gravada. |
| *(sem código, HTTP 403)*        | —                                                   | `PROVIDER_UNAVAILABLE`                                                                                                                 | `PROVIDER_UNAVAILABLE`                | Submeter de novo mais tarde.                                                                     |
| *(sem código, HTTP 404 ou 5xx)* | Falha da borda da Caixa                             | Retentativa automática                                                                                                                 | `TRANSIENT_PROVIDER_EDGE_UNAVAILABLE` | Escrita: aguardar. Consulta: submeter de novo.                                                   |
| *(sem resposta)*                | Timeout                                             | Verificação: nada gravado → `PROVIDER_UNCONFIRMED`; solicitação encontrada → segue o status dela; sem conclusão → `NEEDS_VERIFICATION` | —                                     | Escrita: repetir só após `PROVIDER_UNCONFIRMED`.                                                 |

Na escrita, quando a Caixa aceita a solicitação, o `statusProtocolo` define o desfecho: `1` → `COMPLETED`; `2` → `AWAITING_PROVIDER` (só averbação); `3` → `ENDORSEMENT_DENIED`, `CANCELLATION_DENIED` ou `MAINTENANCE_DENIED`, conforme a operação; qualquer outro valor → `UNKNOWN_PROTOCOL_STATUS`.

{% hint style="info" %}
O limite de taxa da própria Caixa (HTTP `429`) **não** chega até você como erro: a plataforma reprograma a chamada internamente.
{% endhint %}

### Estados de contrato que indicam falha <a href="#catalogo-contrato-estados" id="catalogo-contrato-estados"></a>

| `status`                     | O que aconteceu                                                                                                                                                                                                                 | Onde está o motivo                                                                                                                                                                                                        | O que fazer                                                                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENDORSEMENT_REJECTED`       | Averbação recusada.                                                                                                                                                                                                             | No webhook `CONTRACT_ENDORSEMENT_REJECTED` e no `GET` da operação de averbação. O `GET /contracts/{contractNumber}` **não** traz o motivo.                                                                                | [Retentar a averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md), se a causa mudou.                          |
| `DOCUMENT_GENERATION_FAILED` | A geração da CCB falhou. **Não é terminal**: se a geração for concluída depois (resultado atrasado ou geração refeita pelo suporte), o contrato volta a `AWAITING_SIGNED_DOCUMENT` com o webhook `CONTRACT_DOCUMENT_GENERATED`. | Webhook `CONTRACT_DOCUMENT_GENERATION_FAILED`, em `error.message`.                                                                                                                                                        | Acionar o suporte e aguardar `CONTRACT_DOCUMENT_GENERATED`. Antes de submeter contrato novo, confirme com o suporte: o contrato original ainda pode ser recuperado. |
| `FORMALIZATION_FAILED`       | A formalização falhou.                                                                                                                                                                                                          | Webhook `CONTRACT_FORMALIZATION_FAILED`.                                                                                                                                                                                  | Acionar o suporte.                                                                                                                                                  |
| `REVERSAL_FAILED`            | O estorno da averbação falhou. Não gera webhook.                                                                                                                                                                                | —                                                                                                                                                                                                                         | Acionar o suporte.                                                                                                                                                  |
| `CANCELLED`                  | Contrato cancelado.                                                                                                                                                                                                             | `reason.code` do webhook `CONTRACT_CANCELLED`: `CANCELLED_BY_ORIGINATOR`, `ENDORSEMENT_DENIED_NOT_RETRYABLE`, `ENDORSEMENT_RETRY_WINDOW_EXPIRED`, `DISBURSEMENT_REVISION_EXPIRED` ou `ENDORSEMENT_CANCELLED_BY_OPERATOR`. | Submeter contrato novo, se for o caso.                                                                                                                              |

### Entrega de webhook <a href="#catalogo-entrega" id="catalogo-entrega"></a>

Como a resposta do **seu** endpoint decide a entrega. Detalhes em [Retry e garantias](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/retry-e-garantias.md).

| Sua resposta                                        | O que a plataforma faz                                                                                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `2xx`                                               | Entrega confirmada. O corpo é ignorado.                                                                                                     |
| `3xx`, `5xx`, `408`, `429`, timeout ou erro de rede | Reentrega até 4 vezes, cerca de **1, 5, 30 e 120 minutos** depois de cada falha — 5 chamadas no total. Depois disso, a entrega é cancelada. |
| Demais `4xx`                                        | Cancela a entrega na hora, sem reentrega. Não responda `4xx` para falha transitória.                                                        |

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
