> 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-gtpayroll/guias/erros.md).

# Erros da API

Esta página lista todos os erros que a API Originator devolve, síncronos (resposta HTTP) e assíncronos (webhook ou campo de status), com o gatilho e o que fazer em cada um.

## Formato

Os erros seguem o [RFC 7807](https://tools.ietf.org/html/rfc7807) (Problem Details): `type`, `title`, `status`, `detail` e `instance` na raiz. Os campos extras vêm **dentro de `properties`**, não na raiz.

```json
{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros#business-rule-violation",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Employee não autorizado",
  "instance": "/api/v1/originator/employees/0199a1b2-.../margin",
  "properties": {
    "message": "Employee não autorizado",
    "errorCode": "EMPLOYEE_NOT_AUTHORIZED"
  }
}
```

| Campo                  | Conteúdo                                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `type`                 | URL desta página com o fragmento da seção (ex.: `#conflict`). Agrupa erros da mesma família.  |
| `title`                | Nome curto. Na maioria dos casos é a frase padrão do status HTTP (`Not Found`, `Conflict`).   |
| `status`               | Status HTTP, igual ao da resposta.                                                            |
| `detail`               | Mensagem legível. Pode mudar de texto; não faça `if` sobre ela quando houver `errorCode`.     |
| `properties.message`   | Repete o `detail`.                                                                            |
| `properties.errorCode` | Código estável do erro. **Opcional**: só parte dos erros de regra de negócio tem.             |
| `properties.errors`    | Mapa campo → mensagem, nos erros de validação.                                                |
| demais `properties`    | Específicos do erro (`retryAfter`, `windowEnd`, `violations`, `publicId`…), descritos abaixo. |

## Como tratar

1. **Roteie por `status` + `properties.errorCode`.** O `type` sozinho não identifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422, 429, 500 e 503.
2. **Sem `errorCode`**, o `detail` é a única pista. As regras sem código estão listadas em [Regras de negócio sem `errorCode`](#regras-sem-errorcode).
3. **Depois de qualquer erro, use uma `Idempotency-Key` nova.** A API grava a resposta — inclusive de erro — na chave, e repetir a chave devolve o mesmo erro (ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md)).
4. **Retente só o que é transitório**: `409` de chave em processamento, `423`, `429`, `500`, `502` e `503`. Os demais 4xx exigem mudar a requisição ou o estado do recurso.

### Ordem de avaliação

Num `POST`, as verificações acontecem nesta ordem, e o primeiro erro encerra a requisição:

1. autenticação (`401`/`403`);
2. `Idempotency-Key` (`409` ou replay da resposta gravada);
3. janela de suspensão da Dataprev (`423`);
4. leitura e validação do corpo (`400`);
5. rate limit (`429`);
6. regras de negócio.

Consequência prática: com a janela de suspensão aberta, um corpo inválido recebe `423`, e não `400`.

### Respostas fora do envelope

Três tipos de resposta não trazem `properties.message` nem `errorCode`:

| Caso                                                                                                                           | Formato                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Corpo ilegível, parâmetro de tipo errado, rota inexistente, método não suportado (`405`), `Content-Type` não suportado (`415`) | `type: "about:blank"`, `properties: null`. Ver [Corpo ou parâmetro ilegível](#invalid-request-body).                                      |
| Reprovação de elegibilidade                                                                                                    | `type: "about:blank"`, `title: "Elegibility Violation"`, lista em `properties.violations[]`. Ver [Elegibilidade](#eligibility-violation). |
| Falha ao iniciar assinatura no provedor                                                                                        | `type: "about:blank"`, `title: "Signature provider unavailable"`, `status: 502`.                                                          |

***

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

**HTTP 400.** Bean Validation do corpo: campo obrigatório ausente, formato ou tamanho inválido. `properties.errors` traz um mapa **campo → mensagem**.

```json
{
  "type": "https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros#validation-error",
  "title": "Bean validation error",
  "status": 400,
  "detail": "One or more fields were invalid. See 'errors' for details.",
  "instance": "/api/v1/originator/simulations",
  "properties": {
    "message": "One or more fields were invalid. See 'errors' for details.",
    "errors": {
      "loanAmount": "must be greater than or equal to 0.01",
      "pix.key": "must not be blank"
    }
  }
}
```

* Campos aninhados usam caminho: `pix.key`, `installments[0].dueDate`.
* Regras que cruzam campos aparecem com o nome da regra: `paymentInfoValid`, `authorization.atMostOneStrategyProvided`.
* Um campo com mais de uma violação junta as mensagens com `"; "`.
* As mensagens padrão seguem o header `Accept-Language`.
* Campo desconhecido no JSON **não** gera erro: é ignorado.

**O que fazer:** corrigir os campos listados. Não retentar a mesma requisição.

***

## Corpo ou Parâmetro Ilegível <a href="#invalid-request-body" id="invalid-request-body"></a>

**HTTP 400.** O corpo não pôde ser lido ou um parâmetro de path/query não pôde ser convertido. Hoje essas respostas saem com `type: "about:blank"` e `properties: null`:

| Situação                                                                                     | `detail`                                                |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| JSON malformado, data fora de `yyyy-MM-dd`/ISO-8601, enum desconhecido, tipo errado no corpo | `Failed to read request`                                |
| Parâmetro de query/path com tipo errado (data, enum, número)                                 | `Failed to convert '<parâmetro>' with value: '<valor>'` |

```json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Failed to convert 'status' with value: 'NAO_EXISTE'",
  "instance": "/api/v1/originator/auction/solicitations",
  "properties": null
}
```

Na chave Pix aleatória, envie o tipo `RANDOM` (não `EVP`): `EVP` é rejeitado como enum desconhecido.

**O que fazer:** corrigir o JSON ou o parâmetro.

### Outros erros de protocolo <a href="#invalid-parameter" id="invalid-parameter"></a>

Mesmo formato `about:blank`, sem `properties`:

| HTTP | Situação                                                                                  |
| ---- | ----------------------------------------------------------------------------------------- |
| 404  | Rota inexistente (`No static resource …`). Confira método e path.                         |
| 405  | Método não suportado na rota.                                                             |
| 415  | `Content-Type` diferente de `application/json` (ou de `multipart/form-data` nos uploads). |

***

## Violação de Integridade <a href="#data-integrity-violation" id="data-integrity-violation"></a>

**HTTP 400.** Violação de restrição do banco detectada fora de uma corrida. Na prática, o caso de valor duplicado chega como [`409 #conflict`](#conflict) (`Recurso já existe ou violação de restrição de unicidade.`).

***

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

**HTTP 401.** `detail`: `Token inválido ou ausente`.

Ocorre com header `Authorization` ausente, prefixo diferente de `Bearer` (sensível a maiúsculas), JWT inválido ou expirado, token revogado ou inativo, ou originador removido.

**O que fazer:** obter um token novo (ver [Ambientes e Autenticação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/ambientes-e-autenticacao.md)). Não retentar com o mesmo token.

***

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

**HTTP 403.**

| `title`                            | `detail`                             | Situação                                                                               |
| ---------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| `Access denied`                    | `Token não pertence a um originador` | Token válido de outro perfil, sem permissão de originador. Use o token do originador.  |
| `Originator authentication failed` | `Authentication failed`              | Raro: o originador do token não foi encontrado durante a requisição. Acione o suporte. |

Recusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam `#business-rule-violation`. Ver [403 de regra de negócio](#403).

***

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

**HTTP 404.** O recurso não existe **ou pertence a outro originador** — a API não diferencia os dois casos.

`title` indica o recurso: `Employee not found`, `Contract not found`, `Proposal not found`, `Simulation not found`, `Webhook subscription not found`, `Originator not found`.

Alguns endpoints devolvem o 404 como `#business-rule-violation`, com ou sem `errorCode` (ver [404 de regra de negócio](#404)). Trate os dois `type` da mesma forma.

**O que fazer:** conferir o identificador e o token usado.

***

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

**HTTP 409.** O estado atual impede a operação.

| `detail`                                                                                | Situação                                                                                                                                                                                  | O que fazer                                                                                                                       |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `A request with this idempotency key is currently being processed. Please retry later.` | A mesma `Idempotency-Key` ainda está em processamento.                                                                                                                                    | Aguardar e repetir **com a mesma chave**.                                                                                         |
| `Idempotency key conflict`                                                              | Colisão ao registrar a chave (inclui chave com mais de 255 caracteres).                                                                                                                   | Reenviar com uma chave nova de até 255 caracteres.                                                                                |
| `O recurso foi alterado por outra operação simultânea…`                                 | Duas escritas concorrentes no mesmo recurso.                                                                                                                                              | Reler o recurso e retentar.                                                                                                       |
| `Recurso já existe ou violação de restrição de unicidade.`                              | Duas requisições criando o mesmo recurso ao mesmo tempo (CPF, vínculo, contrato).                                                                                                         | Consultar o recurso antes de retentar.                                                                                            |
| `Já existe uma subscription de webhook para este originator`                            | `POST /webhooks` com subscription existente.                                                                                                                                              | Usar `PUT /webhooks`.                                                                                                             |
| title `Contract cancellation not allowed`                                               | Contrato já assinado, averbado, formalizado ou cancelado. `properties` traz `publicId`, `requestNumber`, `contractNumber`, `contractStatus`, `endorsementStatus` e `formalizationStatus`. | Não retentar. Contrato averbado usa a [desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/desaverbacao.md). |

Os conflitos de regra de negócio com `errorCode` estão em [409 de regra de negócio](#409).

***

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

**HTTP variável.** Regra de negócio violada. Quando existe, o código está em `properties.errorCode`. As tabelas abaixo estão agrupadas por status.

### 400 <a href="#id-400" id="id-400"></a>

| `errorCode`                      | Quando ocorre                                                                                                      | O que fazer                                                                                                         | Endpoints                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `TAC_NOT_ALLOWED`                | `tacAmount` diferente de 0 (positivo ou negativo).                                                                 | Omitir ou enviar 0.                                                                                                 | Simulações, Criar Proposta            |
| `INSTALLMENT_NOT_IN_SIMULATION`  | Parcela informada não existe na simulação.                                                                         | Ajustar `installmentNumber`.                                                                                        | Criar Proposta                        |
| `SIGNED_DOCUMENT_REQUIRED`       | `authorization.signedDocumentBase64` vazio ou só com espaços.                                                      | Enviar o PDF ou remover o campo.                                                                                    | Criar Employee                        |
| `SIGNED_DOCUMENT_INVALID_BASE64` | Base64 inválido.                                                                                                   | Recodificar o PDF em Base64 padrão.                                                                                 | Criar Employee, Enviar Termo Assinado |
| `SIGNED_DOCUMENT_EMPTY`          | O conteúdo decodificado tem 0 bytes.                                                                               | Enviar o PDF.                                                                                                       | Enviar Termo Assinado                 |
| `SIGNED_DOCUMENT_NOT_PDF`        | O conteúdo decodificado não é um PDF. No Criar Employee o status é **422**.                                        | Enviar um PDF.                                                                                                      | Enviar Termo Assinado                 |
| `BQ`                             | Valor desembolsado maior que o valor do empréstimo.                                                                | Corrigir a oferta.                                                                                                  | Submeter Ofertas                      |
| `BL`                             | Valor desembolsado maior ou igual ao total das parcelas.                                                           | Corrigir a oferta.                                                                                                  | Submeter Ofertas                      |
| `OV`                             | CET anual menor ou igual ao mensal.                                                                                | Corrigir a oferta.                                                                                                  | Submeter Ofertas                      |
| `GA`                             | Validade da oferta no passado.                                                                                     | Corrigir a validade.                                                                                                | Submeter Ofertas                      |
| `FI`                             | Garantia ausente, zerada ou acima do saldo/multa proposto, ou `warrantyOffer` ausente em solicitação com garantia. | Ver [Cobertura de Garantias](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/cobertura-de-garantias.md). | Submeter Ofertas                      |
| `FJ`                             | `warrantyOffer` em solicitação sem garantia, ou taxa não menor que a da oferta padrão.                             | Corrigir a oferta.                                                                                                  | Submeter Ofertas                      |
| `INCOMPLETE_DATE_RANGE`          | Só `includedFrom` ou só `includedTo` informado.                                                                    | Enviar as duas datas ou nenhuma.                                                                                    | Escriturações (globais)               |
| —                                | Regra sem código. Ver [Regras de negócio sem `errorCode`](#regras-sem-errorcode).                                  | Ler o `detail`.                                                                                                     | Vários                                |

### 403 <a href="#id-403" id="id-403"></a>

| `errorCode`                      | Quando ocorre                                                                                                                               | O que fazer                                                                                                                                               | Endpoints                                                                 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `ORIGINATOR_OPT_IN_NOT_ENABLED`  | Originador fora da estratégia `ORIGINATOR_MANAGED` enviou trilha ou PDF de autorização. Na trilha, é checado antes do employee.             | Solicitar a habilitação à Giro. Ver [Estratégias de Assinatura](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/estrategias-de-assinatura.md). | Criar Employee (com `authorization`), Criar Trilha, Enviar Termo Assinado |
| `AUCTION_PARTICIPATION_DISABLED` | Originador sem participação no leilão habilitada. Na proposta e no contrato, só quando a operação é de leilão (`proposalNumber` informado). | Solicitar a habilitação à Giro.                                                                                                                           | Listar Solicitações, Submeter Ofertas, Criar Proposta, Criar Contrato     |
| —                                | `Documento não pertence ao employee informado`: o `nsu` é de outro employee.                                                                | Usar o `nsu` do employee do path.                                                                                                                         | Baixar Documento de Autorização                                           |

### 404 <a href="#id-404" id="id-404"></a>

| `errorCode`                     | Quando ocorre                                                                                                                                           | O que fazer                                      | Endpoints                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| `EMPLOYEE_NOT_FOUND`            | Employee inexistente ou de outro originador.                                                                                                            | Conferir o `publicId`.                           | Consultar e Atualizar Margem, Consultar Vínculos Autorizados |
| `REQUEST_NOT_FOUND`             | `requestId` inexistente ou de outro originador.                                                                                                         | Conferir o `requestId`.                          | Consultar Vínculos Autorizados (GET)                         |
| `ENDORSEMENT_NOT_FOUND`         | Contrato sem averbação (não assinado, `CREATED` ou `CANCELLED`).                                                                                        | Para contrato não averbado, usar o cancelamento. | Desaverbar Contrato                                          |
| `GUARANTEE_EXECUTION_NOT_FOUND` | Contrato sem execução de garantia — é o caso normal.                                                                                                    | Aguardar o webhook `GUARANTEE_EXECUTED`.         | Consultar Execução de Garantia                               |
| `TERMINATED_LOAN_NOT_FOUND`     | O número não é contrato do originador nem empréstimo encerrado dele.                                                                                    | Conferir o número.                               | Ajustar Parcelas (empréstimo encerrado)                      |
| —                               | `Employee não encontrado`, `Vínculo não encontrado`, `Request não encontrado`, `Solicitation not found`, `Offer not found`, `Alteração não encontrada`. | Conferir o identificador.                        | Autorização, Consultas Dataprev, Leilão, Término de Vínculo  |

### 409 <a href="#id-409" id="id-409"></a>

| `errorCode`                             | Quando ocorre                                                                                                                                                                                                                                                         | O que fazer                                                                                                                                                          | Endpoints                               |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `EMPLOYEE_INACTIVE`                     | CPF já cadastrado e desativado.                                                                                                                                                                                                                                       | A reativação é feita pelo suporte.                                                                                                                                   | Criar Employee                          |
| `EMPLOYMENT_RELATIONSHIP_TERMINATED`    | Vínculo com data de desligamento na Dataprev.                                                                                                                                                                                                                         | Usar outro vínculo.                                                                                                                                                  | Cadastrar Vínculo                       |
| `INVALID_SIMULATION_TAC`                | Simulação antiga com TAC maior que 0.                                                                                                                                                                                                                                 | Refazer a simulação.                                                                                                                                                 | Criar Proposta                          |
| `AUCTION_OFFER_BUSY`                    | A oferta de leilão vigente do CPF está em uso por outra operação no mesmo instante. Nada foi gravado.                                                                                                                                                                 | Repetir após alguns instantes com uma **nova** `Idempotency-Key`.                                                                                                    | Criar Proposta                          |
| `CONTRACT_NUMBER_ALREADY_USED`          | `contractNumber` já usado pelo originador.                                                                                                                                                                                                                            | Enviar outro número.                                                                                                                                                 | Criar Contrato                          |
| `CONTRACT_ILLEGAL_TRANSITION`           | Upload sobre contrato `CANCELLED` ou `PENDING_PAYMENT_APPROVAL`.                                                                                                                                                                                                      | Não retentar.                                                                                                                                                        | Upload Contrato Assinado                |
| `CONTRACT_NOT_PENDING_PAYMENT_APPROVAL` | Contrato fora de `PENDING_PAYMENT_APPROVAL`.                                                                                                                                                                                                                          | Não retentar.                                                                                                                                                        | Confirmar Aprovação de Pagamento        |
| `EXCLUSION_IN_PROGRESS`                 | Desaverbação já em andamento ou concluída.                                                                                                                                                                                                                            | Aguardar o webhook.                                                                                                                                                  | Desaverbar Contrato                     |
| `ENDORSEMENT_NOT_ENDORSED`              | Averbação ainda não concluída.                                                                                                                                                                                                                                        | Aguardar a averbação ou cancelar o contrato.                                                                                                                         | Desaverbar Contrato                     |
| `CONTRACT_ALREADY_CANCELLED`            | Contrato já cancelado.                                                                                                                                                                                                                                                | Não retentar.                                                                                                                                                        | Desaverbar Contrato                     |
| `CONTRACT_ALREADY_PAID`                 | Contrato `COMPLETED` ou desembolso pago.                                                                                                                                                                                                                              | Não retentar.                                                                                                                                                        | Desaverbar Contrato                     |
| `DISBURSEMENT_IN_PROGRESS`              | Pagamento possivelmente em curso no GTBanker: CCB enviada aguardando confirmação, desembolso em andamento, correção de conta em andamento ou falha de desembolso em análise. O `detail` diz qual. Desaverbar agora poderia deixar o valor pago sem desconto em folha. | Tente novamente após o desfecho do pagamento (`PAYMENT_REVISION` libera a desaverbação; `PAYMENT_SUCCESS` encerra a possibilidade). Sem desfecho, acionar o suporte. | Desaverbar Contrato                     |
| `TERMINATED_LOAN_OPERATION_IN_FLIGHT`   | Outra alteração em processamento sobre o contrato. `properties`: `blockingPublicId`, `status`, `operationType`.                                                                                                                                                       | Consultar a operação bloqueadora.                                                                                                                                    | Ajustar Parcelas (empréstimo encerrado) |
| —                                       | `Proposta já convertida em contrato`, `Proposta em status inválido para criação de contrato`, `Solicitation is not open for offers` (inclui a segunda submissão para a mesma solicitação).                                                                            | Consultar o estado; não retentar.                                                                                                                                    | Criar Contrato, Submeter Ofertas        |

### 413 <a href="#id-413" id="id-413"></a>

| `errorCode`                 | Quando ocorre                                       | O que fazer    | Endpoints             |
| --------------------------- | --------------------------------------------------- | -------------- | --------------------- |
| `SIGNED_DOCUMENT_TOO_LARGE` | PDF decodificado acima de 10 MB (10.485.760 bytes). | Reduzir o PDF. | Enviar Termo Assinado |

### 422 <a href="#id-422" id="id-422"></a>

Requisição válida que não pode ser processada no estado atual do recurso.

| `errorCode`                                           | Quando ocorre                                                                                                                                                                                                                                                                                                                                                            | O que fazer                                                                                                                                                                                                                                                                                          | Endpoints                                           |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `CPF_MISMATCH`                                        | `documentNumber` da trilha ou do termo diferente do CPF do employee.                                                                                                                                                                                                                                                                                                     | Corrigir ou omitir o campo.                                                                                                                                                                                                                                                                          | Criar Employee, Criar Trilha, Enviar Termo Assinado |
| `SIGNED_DOCUMENT_NOT_PDF`                             | O conteúdo do termo não é um PDF.                                                                                                                                                                                                                                                                                                                                        | Enviar um PDF.                                                                                                                                                                                                                                                                                       | Criar Employee                                      |
| `EMPLOYEE_NOT_AUTHORIZED`                             | `dataprevAuthorizationStatus` diferente de `AUTHORIZED`. No `POST /margin`, só quando também não há termo assinado recente para reenviar.                                                                                                                                                                                                                                | Concluir a autorização.                                                                                                                                                                                                                                                                              | Atualizar Margem, Consultas Dataprev                |
| `CPF_INELIGIBLE`                                      | O último termo foi reprovado pela Dataprev como inelegível.                                                                                                                                                                                                                                                                                                              | `POST /margin` reenvia a autorização se o termo tiver menos de 30 dias; senão, colher novo termo.                                                                                                                                                                                                    | Consultar Margem                                    |
| `MARGIN_REFRESH_REQUIRED`                             | `GET /margin` sem margem vigente nem consulta em andamento.                                                                                                                                                                                                                                                                                                              | Chamar [Atualizar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md) e aguardar `MARGIN_QUERY_COMPLETED` (o [`GET` é read-only](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/consultar-margem.md#o-get-read-only)). | Consultar Margem                                    |
| `BOND_NOT_ELIGIBLE`                                   | Vínculo inelegível sem `forceIneligible: true`.                                                                                                                                                                                                                                                                                                                          | Reenviar com `forceIneligible: true` para consultar mesmo assim.                                                                                                                                                                                                                                     | Consultar Margem por Vínculo                        |
| `EMPLOYEE_GENDER_REQUIRED`                            | O originador exige gênero e o employee não tem.                                                                                                                                                                                                                                                                                                                          | Atualizar o cadastro do employee.                                                                                                                                                                                                                                                                    | Criar Contrato                                      |
| `INSURANCE_PREMIUM_MISMATCH`                          | `insurancePremiumAmount` diferente do seguro da simulação.                                                                                                                                                                                                                                                                                                               | Enviar o mesmo valor ou omitir.                                                                                                                                                                                                                                                                      | Criar Contrato                                      |
| `POS_ALIAS_NOT_FOUND`                                 | `pointOfSaleAlias` não cadastrado.                                                                                                                                                                                                                                                                                                                                       | Usar um alias cadastrado ou omitir.                                                                                                                                                                                                                                                                  | Criar Contrato                                      |
| `INVALID_SIGNATURE_GEOLOCATION`                       | Coordenada `(0,0)` ou fora de ±90 (latitude) / ±180 (longitude).                                                                                                                                                                                                                                                                                                         | Enviar a coordenada real em grau decimal.                                                                                                                                                                                                                                                            | Upload Contrato Assinado                            |
| `AUCTION_OFFER_NOT_FOUND`                             | `proposalNumber` que não é oferta do originador para o CPF/`solicitationId`, já convertida ou já reivindicada por outra proposta.                                                                                                                                                                                                                                        | Corrigir ou remover o campo.                                                                                                                                                                                                                                                                         | Criar Proposta                                      |
| `AUCTION_ACTIVE_OFFER_RATE_EXCEEDED`                  | O CPF tem oferta de leilão vigente (sua ou de outro originador) e a taxa mensal da proposta está acima do teto. `properties.maxMonthlyInterestRate` traz o teto (%, 2 casas) — a menor taxa entre as ofertas vigentes do CPF. A oferta em si nunca é exposta.                                                                                                            | Refazer a simulação com taxa mensal menor ou igual ao teto.                                                                                                                                                                                                                                          | Criar Proposta                                      |
| `AUCTION_ORIGINATOR_PREFIX_MISSING`                   | Originador sem prefixo Dataprev configurado.                                                                                                                                                                                                                                                                                                                             | Solicitar a configuração à Giro.                                                                                                                                                                                                                                                                     | Listar Solicitações, Submeter Ofertas               |
| `FI`                                                  | Cobertura de garantia FGTS fora da regra. A mensagem traz o valor esperado.                                                                                                                                                                                                                                                                                              | Ajustar conforme [Cobertura de Garantias](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/cobertura-de-garantias.md).                                                                                                                                                                     | Criar Proposta, Submeter Ofertas                    |
| `FORMALIZATION_NOT_CORRECTABLE`                       | A conta de desembolso não pode ser corrigida no estado atual. O `detail` diz o motivo: correção sem `ticket` com desembolso fora de falha/retentativa; desaverbação em andamento ou concluída, ou contrato cancelado; desembolso já pago; envio da CCB suspenso por pedido de desaverbação (sem `ticket`); ou outra correção de conta ainda em andamento (com `ticket`). | Sem `ticket` fora de falha: aguardar `PAYMENT_REVISION` e usar o ticket. Envio suspenso: acionar o suporte. Correção em andamento: aguardar o desfecho dela (janela de 5 minutos). Demais casos: não retentar.                                                                                       | Atualizar Conta de Desembolso                       |
| `TERMINATED_LOAN_CONTRACT_NUMBER_UNUSABLE`            | Número de contrato Dataprev inválido para a operação.                                                                                                                                                                                                                                                                                                                    | Acionar o suporte.                                                                                                                                                                                                                                                                                   | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_NOT_IN_STATUS_15`                    | Sem evidência de encerramento do vínculo (situação 15).                                                                                                                                                                                                                                                                                                                  | Aguardar a próxima ingestão.                                                                                                                                                                                                                                                                         | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_CONTRACT_MIGRATED`                   | Contrato já migrado.                                                                                                                                                                                                                                                                                                                                                     | Não retentar.                                                                                                                                                                                                                                                                                        | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_WORKER_MISMATCH`                     | `cpf` diferente do trabalhador do contrato.                                                                                                                                                                                                                                                                                                                              | Corrigir o `cpf`.                                                                                                                                                                                                                                                                                    | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_EVIDENCE_INCOMPLETE`                 | Evidência de encerramento sem dados suficientes (`missingFields`/`malformedFields`).                                                                                                                                                                                                                                                                                     | Acionar o suporte.                                                                                                                                                                                                                                                                                   | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_ALTERATION_NO_CHANGE`                | Nenhum valor difere do atual.                                                                                                                                                                                                                                                                                                                                            | Enviar uma alteração real.                                                                                                                                                                                                                                                                           | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_INSTALLMENTS_ABOVE_LIMIT`            | Mais de 84 parcelas.                                                                                                                                                                                                                                                                                                                                                     | Reduzir.                                                                                                                                                                                                                                                                                             | Ajustar Parcelas                                    |
| `TERMINATED_LOAN_INSTALLMENT_AMOUNT_ABOVE_REGISTERED` | Parcela acima da registrada.                                                                                                                                                                                                                                                                                                                                             | Reduzir.                                                                                                                                                                                                                                                                                             | Ajustar Parcelas                                    |

### 429 e 503 de regra de negócio <a href="#id-503" id="id-503"></a>

| HTTP | `errorCode`                                | Quando ocorre                                                                          | O que fazer                                                                                 | Endpoints                                          |
| ---- | ------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| 503  | `SERVICE_UNAVAILABLE_LOANSIMULATOR`        | Motor de simulação indisponível. `detail`: `External service temporarily unavailable`. | Retentar com backoff e chave nova.                                                          | Simulações                                         |
| 503  | `SERVICE_UNAVAILABLE_GTBANKER`             | Serviço de desembolso indisponível. Não garante que o ticket continua válido.          | Retentar; se voltar 400 de ticket consumido, aguardar `PAYMENT_SUCCESS`/`PAYMENT_REVISION`. | Atualizar Conta de Desembolso                      |
| 503  | `SERVICE_UNAVAILABLE_GTPAYROLL_DISPATCHER` | Integração Dataprev indisponível.                                                      | Retentar.                                                                                   | Criar Trabalhador, Solicitação Extra (homologação) |

### Regras de negócio sem `errorCode` <a href="#regras-sem-errorcode" id="regras-sem-errorcode"></a>

Todas são **HTTP 400** `#business-rule-violation`. O texto do `detail` é o identificador.

| Domínio     | `detail`                                                                                                    | Quando ocorre                                                                                                                                                |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Employees   | `Documento do empregador inválido: <documento>`                                                             | CNPJ/CPF do empregador inválido.                                                                                                                             |
| Simulações  | `Vínculo empregatício não encontrado: <id>`                                                                 | Vínculo inexistente ou de outro employee.                                                                                                                    |
| Simulações  | `O primeiro vencimento deve ser no dia 28. Informado: dd/MM/aaaa`                                           | `firstDueDate` fora do dia 28.                                                                                                                               |
| Simulações  | `O primeiro vencimento deve seguir o calendário Dataprev. Primeiro vencimento mínimo permitido: dd/MM/aaaa` | Vencimento antes do mínimo.                                                                                                                                  |
| Simulações  | `Simulação rejeitada pela validação de Valor Presente da Dataprev. …`                                       | Valor financiado abaixo do piso de valor presente.                                                                                                           |
| Simulações  | `Vínculo empregatício não possui margem disponível.`                                                        | Margem do vínculo nunca consultada. Chame [Atualizar Margem](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/margem/atualizar-margem.md). |
| Simulações  | `Simulação reversa não convergiu para o valor de parcela informado.`                                        | Não existe valor de empréstimo para a parcela pedida. Ajuste a parcela ou o prazo.                                                                           |
| Propostas   | `Simulação não encontrada: <id>`                                                                            | Simulação inexistente ou de outro employee.                                                                                                                  |
| Propostas   | `Campos obrigatórios ausentes ou inválidos: <lista>`                                                        | Modo manual incompleto, `dueDate` no passado ou taxa anual incoerente com a mensal.                                                                          |
| Propostas   | `A quantidade de parcelas (N) deve ser igual a installmentCount (M)`                                        | Modo manual com parcelas e `installmentCount` divergentes.                                                                                                   |
| Contratos   | `CPF do colaborador é obrigatório…` / `Data de nascimento…` / `Telefone do funcionário…`                    | Assinatura pela Giro com cadastro do employee incompleto.                                                                                                    |
| Contratos   | `Data da primeira/última parcela é obrigatória para criar o contrato`                                       | Datas omitidas e proposta sem data de aniversário.                                                                                                           |
| Contratos   | `O primeiro vencimento deve ser no mínimo 30 dias após a data do contrato…`                                 | Carência mínima não respeitada.                                                                                                                              |
| Contratos   | `Número do contrato é obrigatório quando… ORIGINATOR_PROVIDED…` / `contractNumber inválido…`                | Estratégia de numeração do originador.                                                                                                                       |
| Contratos   | `Contrato não possui URL de assinatura`                                                                     | Reenvio de link sem assinatura iniciada.                                                                                                                     |
| Contratos   | `Upload de contrato assinado disponível apenas para ORIGINATOR_MANAGED`                                     | Estratégia de assinatura diferente.                                                                                                                          |
| Contratos   | `Contrato já foi processado - Status: <status>`                                                             | Contrato já assinado ou adiante.                                                                                                                             |
| Contratos   | `Erro ao processar contrato assinado` / `Erro ao fazer upload de imagem biometrica`                         | Falha ao processar os arquivos — pode ser transitória. Consulte o contrato e retente com chave nova.                                                         |
| Autorização | `Documento de autorização não encontrado para NSU: <nsu>`                                                   | `nsu` inexistente, de outro originador ou de outro employee.                                                                                                 |
| Autorização | `Upload de documento de autorização assinado disponível apenas para ORIGINATOR_MANAGED`                     | Estratégia de assinatura diferente.                                                                                                                          |
| Autorização | `Erro ao processar documento de autorização assinado`                                                       | Falha ao processar o arquivo — pode ser transitória. Consulte o status e retente com chave nova.                                                             |
| Leilão      | `Redirect URL must use HTTPS protocol` / `…valid host` / `…is malformed`                                    | `redirectUrl` inválida.                                                                                                                                      |
| Desembolso  | `Erro na atualização de conta: <mensagem>`                                                                  | Recusa do serviço de desembolso para o ticket informado.                                                                                                     |
| Desembolso  | `Originator sem credencial GTBanker…` / `Metadata GTBanker inválida…`                                       | Configuração do originador na Giro. Acione o suporte.                                                                                                        |

***

## Elegibilidade <a href="#eligibility-violation" id="eligibility-violation"></a>

**HTTP 400**, `type: "about:blank"`, `title: "Elegibility Violation"`, `detail: "Elegibility validation failed"`. Não há `properties.message`; cada regra reprovada vem em `properties.violations[]`.

```json
{
  "type": "about:blank",
  "title": "Elegibility Violation",
  "status": 400,
  "detail": "Elegibility validation failed",
  "properties": {
    "violations": [
      {
        "code": "MAX_TERM_EXCEEDED",
        "message": "Prazo máximo excedido",
        "field": "installmentCount",
        "currentValue": "96",
        "requiredValue": "84"
      }
    ]
  }
}
```

| `code`                                                                                                                                                                                                                                                                              | Ajustável na requisição?                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `MIN_LOAN_AMOUNT_NOT_MET`, `MAX_LOAN_AMOUNT_EXCEEDED`, `MIN_TERM_NOT_MET`, `MAX_TERM_EXCEEDED`, `MARGIN_EXCEEDED`, `MAX_EFFECTIVE_COST_EXCEEDED`                                                                                                                                    | Sim: ajuste valor, prazo ou parcela.                   |
| `MARGIN_NOT_AVAILABLE`                                                                                                                                                                                                                                                              | Atualize a margem e simule de novo.                    |
| `MIN_AGE_NOT_MET`, `MAX_AGE_EXCEEDED`, `BIRTH_DATE_NOT_AVAILABLE`, `MIN_EMPLOYMENT_TENURE_NOT_MET`, `ADMISSION_DATE_NOT_AVAILABLE`, `MAX_ACTIVE_CONTRACTS_EXCEEDED`, `EMPLOYER_MIN_EXISTENCE_NOT_MET`, `EMPLOYER_IS_MEI`, `POLITICALLY_EXPOSED_PERSON`, `SUSPENSION_SCORE_EXCEEDED` | Não: o trabalhador ou o vínculo não atende à política. |

Endpoints: Criar Simulação, Criar Simulação por Parcela (só `MARGIN_EXCEEDED`), Criar Proposta e Criar Contrato (`MAX_EFFECTIVE_COST_EXCEEDED`). Regras em [Elegibilidade](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/elegibilidade.md).

***

## Garantia / Cobertura (FGTS) <a href="#guarantee-coverage" id="guarantee-coverage"></a>

A Dataprev reprova operações com garantia com **`FI`** (garantia/cobertura inválida) ou **`FJ`** (proposta/regra de garantia inválida), ambos permanentes. Parte dessas regras é validada antes de chamar a Dataprev e volta como [`400`](#400) (Submeter Ofertas) ou [`422`](#422) (Criar Proposta, Submeter Ofertas) com `errorCode` `FI`/`FJ`. Regras em [Cobertura de Garantias (FGTS)](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/cobertura-de-garantias.md).

***

## Janela de Suspensão da Dataprev <a href="#dataprev-suspension-window" id="dataprev-suspension-window"></a>

**HTTP 423**, `title: "Locked"`, `errorCode: DATAPREV_SUSPENSION_WINDOW`. A Dataprev está na janela de suspensão (virada de competência) e a operação não pode ser enviada.

* `properties.windowEnd`: fim previsto da janela, em data/hora **sem fuso**. Use o `Retry-After` como referência de espera.
* Header `Retry-After`: segundos até o fim da janela.
* A recusa acontece antes da validação do corpo.
* A resposta **fica gravada na `Idempotency-Key`**.

**O que fazer:** aguardar o `Retry-After` ou o webhook `DATAPREV_WINDOW_CLOSED` e reenviar com **chave nova**.

Endpoints sujeitos: Criar Employee, Cadastrar Vínculo, Enviar Termo Assinado, Criar Documento de Autorização, Upload Documento Assinado, Atualizar Margem (o `GET` não é bloqueado), criação das Consultas Dataprev (vínculos, margem por vínculo, FGTS), Criar Contrato, Reenviar Link, Upload Contrato Assinado, Cancelar e Desaverbar Contrato, Submeter Ofertas. A Criar Trilha **não** é bloqueada.

***

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

**HTTP 429.** Limite de requisições por janela excedido. `detail`: `Too many requests. Please try again in N seconds.`

* Headers `Retry-After` (segundos) e `X-RateLimit-Reset` — presentes **só** no 429.
* Corpo: `properties.retryAfter` (segundos), `properties.limit` e `properties.resetAt`. `resetAt` e `X-RateLimit-Reset` são epoch em **milissegundos**.
* O limite de cada endpoint está na página dele. A janela padrão é de 1 segundo; Cadastrar Vínculo usa janela de 1 minuto.

**O que fazer:** aguardar o `Retry-After` e reenviar com uma **nova** `Idempotency-Key`: com a mesma chave, a API repete o `429` guardado (ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md)).

***

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

**HTTP 500.** Erro inesperado na plataforma. `detail`: `Erro interno. Consulte os logs do servidor.`

| `errorCode` | Quando ocorre                                                  | Endpoints        |
| ----------- | -------------------------------------------------------------- | ---------------- |
| —           | Erro sem tratamento específico.                                | Todos            |
| `SE`        | Falha ao gerar o número da proposta da oferta. Nada é gravado. | Submeter Ofertas |

**O que fazer:** retentar com chave nova. Persistindo, abrir chamado com o `instance` e o horário da requisição.

***

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

**HTTP 502** (ou o status repassado). Falha em serviço externo.

| HTTP      | `errorCode`                                  | Quando ocorre                                                                                       | O que fazer                     | Endpoints                                                                                                      |
| --------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| 502       | —                                            | title `Document processing error`, detail `Erro ao processar documento. Tente novamente.`           | Retentar com chave nova.        | Criar Employee (com PDF), Enviar Termo Assinado, Baixar Documento de Autorização, Baixar Documento do Contrato |
| 502 / 500 | `LOAN_SIMULATOR_ERROR`                       | Resposta inválida do motor de simulação.                                                            | Retentar; persistindo, suporte. | Simulações                                                                                                     |
| 4xx       | `LOAN_SIMULATOR_ERROR`                       | O motor de simulação recusou os parâmetros; o status e a mensagem são repassados.                   | Ajustar os parâmetros.          | Simulações                                                                                                     |
| 4xx       | —                                            | Homologação: a Dataprev recusou a operação. Detalhe em `properties.upstream` ou `properties.erros`. | Ler o detalhe.                  | Criar Trabalhador, Solicitação Extra                                                                           |
| 503       | `UPSTREAM_SERVER_ERROR_GTPAYROLL_DISPATCHER` | Erro na integração Dataprev. `properties.service` e `properties.upstreamStatus`.                    | Retentar.                       | Criar Trabalhador, Solicitação Extra                                                                           |

***

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

**HTTP 503.** Indisponibilidade momentânea da plataforma. `properties.retryAfter` = 5 (segundos); não há header `Retry-After`.

**O que fazer:** retentar após 5 segundos com chave nova. Os 503 de serviço externo estão em [429 e 503 de regra de negócio](#503).

***

## Erros Assíncronos <a href="#async" id="async"></a>

Parte das falhas acontece depois da resposta `202` e chega por **webhook** ou só pelo **status** do recurso. Payloads completos em [Eventos e Payloads](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/eventos-e-payloads.md).

{% hint style="warning" %}
O `errorCode` dos webhooks **não** é um vocabulário único. Margem e autorização usam códigos semânticos (`CPF_NOT_FOUND_OR_INELIGIBLE`); listagem de vínculos, FGTS, averbação e ajuste de parcelas repassam a sigla da Dataprev (`CB`, `HU`). O mesmo CPF inelegível chega como `CB` num evento e `CPF_NOT_FOUND_OR_INELIGIBLE` no outro.
{% endhint %}

### Por webhook

| Evento                                                                                                             | `errorCode` / campo                                                                                               | Quando ocorre                                                                                                                                                                         | O que fazer                                                                                   |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `MARGIN_QUERY_FAILED`                                                                                              | `CPF_NOT_FOUND_OR_INELIGIBLE`, `EMPLOYMENT_RELATIONSHIP_INELIGIBLE`, `WORKER_NOT_FOUND`                           | Dataprev recusou (`CB`, `HU`, `TA`).                                                                                                                                                  | Não retentar; revisar o cadastro.                                                             |
| `MARGIN_QUERY_FAILED`                                                                                              | `QUERY_EXPIRED`                                                                                                   | Consulta por vínculo sem resultado após 30 minutos.                                                                                                                                   | Retentar a consulta.                                                                          |
| `MARGIN_QUERY_FAILED`                                                                                              | `RETRY_EXHAUSTED`                                                                                                 | Retentativas esgotadas.                                                                                                                                                               | Retentar mais tarde.                                                                          |
| `MARGIN_QUERY_FAILED`, `AUTHORIZATION_FAILED`                                                                      | `NEEDS_VERIFICATION_TIMEOUT`                                                                                      | A Dataprev não confirmou nem descartou a operação e a verificação não fechou no prazo. Efeito desconhecido.                                                                           | A plataforma não reenvia sozinha; acionar o suporte antes de repetir.                         |
| `MARGIN_QUERY_FAILED`, `AUTHORIZATION_FAILED`                                                                      | `ADMIN_FAIL`                                                                                                      | Operador da plataforma encerrou a operação como falha após verificação manual. Efeito na Dataprev pode ser desconhecido.                                                              | A plataforma não reenvia sozinha; acionar o suporte antes de repetir.                         |
| `MARGIN_QUERY_FAILED`                                                                                              | `UNKNOWN_DATAPREV_ERROR`                                                                                          | Outro código Dataprev, ou autorização expirada/ausente (ver `reason`).                                                                                                                | Se a `reason` fala de token ou termo, reautorizar; senão, suporte.                            |
| `MARGIN_QUERY_FAILED`, `AUTHORIZATION_FAILED`, `AUTHORIZED_BONDS_LISTING_FAILED`, `FGTS_AVAILABILITY_QUERY_FAILED` | `DATAPREV_SUSPENSION_WINDOW`                                                                                      | A janela de suspensão abriu com a operação na fila.                                                                                                                                   | Aguardar `DATAPREV_WINDOW_CLOSED` e reenviar.                                                 |
| `MARGIN_QUERY_COMPLETED`                                                                                           | `status`: `NO_BONDS` / `NOT_ELIGIBLE`                                                                             | Margem automática concluída sem vínculo ou sem vínculo elegível. **Não** sai `MARGIN_QUERY_FAILED`.                                                                                   | Tratar como resultado final sem margem.                                                       |
| `AUTHORIZED_BONDS_LISTING_FAILED`                                                                                  | sigla Dataprev (`CB`, `HU`, `TA`…)                                                                                | Listagem recusada pela Dataprev.                                                                                                                                                      | Não retentar em código permanente.                                                            |
| `AUTHORIZED_BONDS_LISTING_FAILED`                                                                                  | `RETRY_EXHAUSTED` / `UNKNOWN`                                                                                     | Falha transitória.                                                                                                                                                                    | Retentar.                                                                                     |
| `FGTS_AVAILABILITY_QUERY_FAILED`                                                                                   | sigla Dataprev ou código `Cxx` da Caixa                                                                           | Recusa da Dataprev/Caixa. `C02`, `C18`, `C25` e `C32` são transitórios.                                                                                                               | `Cxx` transitório: retentar; demais: corrigir ou solicitar autorização FGTS.                  |
| `FGTS_AVAILABILITY_QUERY_FAILED`                                                                                   | `PROVIDER_ERROR`                                                                                                  | A Dataprev rejeitou a consulta sem informar código.                                                                                                                                   | Ver `reason`; persistindo, suporte.                                                           |
| `FGTS_AVAILABILITY_QUERY_FAILED`                                                                                   | `RETRY_EXHAUSTED` / `UNKNOWN`                                                                                     | Falha transitória.                                                                                                                                                                    | Retentar.                                                                                     |
| `AUTHORIZATION_FAILED`                                                                                             | `CPF_NOT_FOUND_OR_INELIGIBLE`, `EMPLOYMENT_RELATIONSHIP_INELIGIBLE`, `WORKER_NOT_FOUND`, `UNKNOWN_DATAPREV_ERROR` | Autorização recusada; o termo fica inelegível.                                                                                                                                        | Corrigir o cadastro e reautorizar.                                                            |
| `AUTHORIZATION_FAILED`                                                                                             | `RETRY_EXHAUSTED`                                                                                                 | Falha transitória — mas o `status` vem `INELIGIBLE` e o termo também.                                                                                                                 | Reenviar a autorização mais tarde.                                                            |
| `AUTHORIZATION_EXPIRED`                                                                                            | `status: EXPIRED`                                                                                                 | A Dataprev informou autorização digital vencida (`OI`). Substitui o `AUTHORIZATION_FAILED`.                                                                                           | Reiniciar a autorização.                                                                      |
| `AUTHORIZATION_DOCUMENT_FAILED`                                                                                    | `RETRY_EXHAUSTED`, `SIGNATURE_REJECTED`, `SIGNATURE_EXPIRED`, `SIGNATURE_CANCELLED`, `FRAUD_DETECTED`             | Falha na geração ou na assinatura do termo.                                                                                                                                           | Gerar novo termo.                                                                             |
| `ENDORSEMENT_FAILED`                                                                                               | sigla Dataprev (`AO`, `BL`, `BQ`, `CB`, `HU`, `HV`, `HW`…)                                                        | Averbação recusada — toda recusa da Dataprev é permanente. O contrato continua `SIGNED`.                                                                                              | Corrigir o dado e criar novo contrato.                                                        |
| `ENDORSEMENT_FAILED`                                                                                               | `INSUFFICIENT_MARGIN_PRE_ENDORSEMENT`, `ANNUAL_RATE_INCONSISTENT_PRE_ENDORSEMENT`, `FI`, `FJ`                     | Validação anterior ao envio à Dataprev.                                                                                                                                               | Refazer simulação e proposta.                                                                 |
| `ENDORSEMENT_FAILED`                                                                                               | `AUCTION_OFFER_RATE_EXCEEDED_PRE_ENDORSEMENT`, `AUCTION_OFFER_WARRANTY_MISMATCH_PRE_ENDORSEMENT`                  | O CPF tem oferta de leilão vigente e a CCB não cabe nela: taxa mensal acima do teto ou garantia incompatível. Nada foi enviado à Dataprev; o contrato continua `SIGNED`.              | Criar nova proposta: a criação devolve `422` `AUCTION_ACTIVE_OFFER_RATE_EXCEEDED` com o teto. |
| `ENDORSEMENT_FAILED`                                                                                               | `AUCTION_OFFER_EXPIRED_PRE_ENDORSEMENT`, `AUCTION_OFFER_SOLICITATION_CONSUMED_PRE_ENDORSEMENT`                    | A oferta referenciada pela proposta venceu, ou a solicitação dela já foi averbada por outra proposta.                                                                                 | Não retentar esta CCB; consultar as solicitações abertas do CPF.                              |
| `ENDORSEMENT_FAILED`                                                                                               | `AUCTION_PROGRAM_NOT_CONFIGURED_PRE_ENDORSEMENT`                                                                  | A CCB seria vinculada a uma oferta sua e o programa de leilão não está configurado na credencial de formalização.                                                                     | Solicitar à Giro a configuração do programa de leilão.                                        |
| `ENDORSEMENT_FAILED`                                                                                               | `AUCTION_OFFER_CLAIM_CONTENTION_TIMEOUT`                                                                          | A oferta vigente do CPF ficou indisponível (em uso por outra CCB) além do prazo de expiração de contratos não averbados, contado da assinatura. O contrato fica elegível à expiração. | Aguardar a expiração ou cancelar o contrato.                                                  |
| `ENDORSEMENT_RETRYING`                                                                                             | `AUCTION_OFFER_CLAIM_CONTENTION`                                                                                  | A oferta vigente do CPF está em uso por outra CCB neste instante. Não consome tentativa e o evento sai só na primeira vez.                                                            | Aguardar.                                                                                     |
| `ENDORSEMENT_FAILED`                                                                                               | `null`                                                                                                            | Retentativas esgotadas por falha de infraestrutura.                                                                                                                                   | Acionar o suporte ou recriar o contrato.                                                      |
| `ENDORSEMENT_RETRYING`                                                                                             | `failureReason`                                                                                                   | Falha transitória; até 3 tentativas a cada 15 minutos.                                                                                                                                | Aguardar.                                                                                     |
| `ENDORSEMENT_EXCLUSION_FAILED`                                                                                     | `errorCode: null`; código em `failureReason` como `[XX] …`                                                        | Desaverbação recusada; o contrato volta a `ENDORSED`.                                                                                                                                 | Ler o código no `failureReason`.                                                              |
| `CONTRACT_SIGNING_FAILED`                                                                                          | `SIGNATURE_REJECTED`, `SIGNATURE_EXPIRED`, `SIGNATURE_CANCELLED`, `FRAUD_DETECTED`                                | Assinatura recusada ou vencida. O contrato é **cancelado**.                                                                                                                           | Criar novo contrato.                                                                          |
| `CONTRACT_SIGNING_FAILED`, `CONTRACT_DOCUMENT_FAILED`, `CONTRACT_REGISTRATION_FAILED`                              | `RETRY_EXHAUSTED`                                                                                                 | Retentativas esgotadas. O contrato **não** é cancelado.                                                                                                                               | Consultar o contrato; recriar ou acionar o suporte.                                           |
| `CONTRACT_FORMALIZATION_FAILED`                                                                                    | `RETRY_EXHAUSTED`                                                                                                 | Desembolso falhou após as retentativas (cerca de 20 horas) ou imediatamente por regra de negócio. `rejectionReason` traz o motivo.                                                    | Corrigir a conta (`PUT /disbursement-accounts`) ou acionar o suporte.                         |
| `PAYMENT_REVISION` / `PAYMENT_FAILURE`                                                                             | `dados.erro.codigo`                                                                                               | Código do serviço de desembolso, repassado sem tradução.                                                                                                                              | `PAYMENT_REVISION`: enviar nova conta com o ticket; `PAYMENT_FAILURE`: aguardar a Giro.       |
| `TERMINATED_LOAN_ALTERATION_FAILED`                                                                                | `providerErrorCode`: sigla Dataprev ou `RETRY_EXHAUSTED` / `DATAPREV_SUSPENSION_WINDOW` / `UNKNOWN`               | Ajuste de parcelas recusado ou falha transitória.                                                                                                                                     | Recusa: corrigir; demais: retentar.                                                           |

### Sem webhook

Estes desfechos só aparecem consultando o recurso:

| Recurso                                    | Estado                                                       | Quando ocorre                                                                   | O que fazer                                    |
| ------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------- |
| Autorização (`GET …/authorization/status`) | `EXPIRED`                                                    | Termo vencido por tempo.                                                        | Controlar `termExpiresAt` e reautorizar antes. |
| Autorização                                | `NOT_STARTED`                                                | Após `AUTHORIZATION_FAILED` de employee nunca autorizado.                       | Usar o webhook como fonte da falha.            |
| Termo de autorização                       | `EXPIRED` / `SUPERSEDED`                                     | Termo pendente vencido, ou termo assinado substituído.                          | Gerar novo termo.                              |
| Averbação                                  | `RETRYING` com `OUTSIDE_OPERATING_HOURS`                     | Fora da janela operacional da Dataprev (06h–22h) ou janela de suspensão aberta. | Aguardar; a averbação segue sozinha.           |
| Contrato                                   | `CANCELLED`, `rejectionReason: "Falha na geração do PDF: …"` | Falha ao gerar o documento do contrato.                                         | Criar novo contrato.                           |
| Oferta de leilão                           | `REJECTED`                                                   | Oferta recusada pela Dataprev.                                                  | Consultar as ofertas.                          |
| Proposta / simulação                       | `EXPIRED`                                                    | Vencimento diário.                                                              | Criar de novo.                                 |

### Entrega de webhooks

Seu endpoint responder `2xx` conclui a entrega. `4xx` **cancela** a entrega na hora, sem retentativa; qualquer outra resposta é retentada em 1, 5, 30, 120 e 360 minutos. Nunca responda `4xx` a um evento válido. Ver [Retry e Garantias de Entrega](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/retry-e-garantias.md).
