> 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/api-reference/contratos/retentar-averbacao.md).

# Retentar Averbação do Contrato

Solicita uma **nova tentativa de averbação** para um contrato cuja averbação foi recusada pela Caixa — contrato em `ENDORSEMENT_REJECTED`, sinalizado pelo evento [`CONTRACT_ENDORSEMENT_REJECTED`](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md). A retentativa **reusa o mesmo `reserveIdentifier`**, que é a chave da reserva junto à Caixa: **não nasce reserva nova** e o contrato volta a `PENDING_ENDORSEMENT`.

{% hint style="info" %}
Esta operação é **assíncrona**: a resposta `202` confirma apenas que o pedido foi encaminhado. O desfecho chega por [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) (`source = CONTRACT`) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) do `GET /api/v1/fgts/contracts/{contractNumber}`.
{% endhint %}

{% hint style="warning" %}
**O `202` não significa "retentativa autorizada".** Significa "pedido encaminhado". Se o teto de tentativas já tiver sido atingido, a recusa **não** cabe nesta resposta — ela chega **depois, por webhook**, como `CONTRACT_ENDORSEMENT_REJECTED`. Ver [Como a recusa chega](#como-a-recusa-chega).
{% endhint %}

## Quando usar

Depois de receber `CONTRACT_ENDORSEMENT_REJECTED` no webhook, ou ao ver o contrato em `ENDORSEMENT_REJECTED` na [consulta](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md).

**Você quase nunca precisa classificar o erro da Caixa para decidir.** Fora o código 52, tratado no aviso abaixo, não há taxonomia que separe falhas "retentáveis" de "terminais": se a averbação chegou à Caixa e foi recusada, ela é retentável enquanto houver tentativa disponível e o contrato ainda estiver em `ENDORSEMENT_REJECTED`.

O que muda essa conclusão são as falhas que **não chegaram à Caixa** — em especial a recusa por `reserveIdentifier` duplicado, em que uma retentativa colidiria de novo. Ela não consome tentativa, e o caminho é submeter um contrato novo. A lista completa de casos não-retentáveis está em [Retentativa por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md#quando-usar).

**Só contratos em `ENDORSEMENT_REJECTED` são elegíveis.** Qualquer outro status responde `409 CONTRACT_INVALID_STATUS`.

{% hint style="warning" %}
**`ENDORSEMENT_REJECTED` não espera para sempre.** Sem retentativa dentro da janela, a Giro cancela o contrato e emite `CONTRACT_CANCELLED` com `reason.code = ENDORSEMENT_RETRY_WINDOW_EXPIRED`; a partir daí o `409 CONTRACT_INVALID_STATUS` passa a valer também para ele. Recusa por **código 52** da Caixa ("Trabalhador já possui quantidade máxima permitida de operação de reserva") é cancelada na hora, com `ENDORSEMENT_DENIED_NOT_RETRYABLE` — retentar bateria no mesmo teto. Nos dois casos o contrato encerrado não volta: submeta um contrato novo.
{% endhint %}

## Teto de tentativas

São no máximo **3 retentativas** por reserva, ou seja **4 tentativas no total** contando a averbação original. O contador é mantido pela Giro e é **por reserva** — não é reiniciado por um novo pedido de retentativa.

Antes de qualquer recusa chegar até você, a Giro já insistiu sozinha: erro **transitório** da Caixa é retentado **a cada 15 minutos por até 72 horas**, com consulta pelo `reserveIdentifier` antes de cada reenvio. E **cada retentativa sua abre uma janela nova de 72 horas** — no pior caso, **12 dias** até a reserva se esgotar de vez. Detalhamento em [Retentativa por identificador](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md#antes-de-retentar).

{% hint style="warning" %}
**Envie `Idempotency-Key`.** O header é opcional, mas aqui a omissão custa caro: sem ele não há deduplicação nenhuma, e um duplo-clique **gasta duas das suas quatro tentativas**. Use uma chave distinta por tentativa lógica e reenvie a **mesma** chave se precisar repetir a requisição por timeout ou erro de rede.
{% endhint %}

## Como a recusa chega

Esta rota e a [retentativa por reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) **não se comportam igual** quando o teto estoura:

| Rota                                                                                                                                                                                                  | Recusa por teto                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [Por reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) (`POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`) | **Síncrona**, na própria resposta: `409` com `errorCode = ENDORSEMENT_RETRY_LIMIT_EXCEEDED`.                   |
| **Por contrato** (esta página)                                                                                                                                                                        | **Assíncrona**: a resposta é sempre `202` e a recusa chega depois, no webhook `CONTRACT_ENDORSEMENT_REJECTED`. |

Na prática: nesta rota o `202` **não** confirma que a tentativa foi autorizada — confirma apenas que o pedido foi aceito. O desfecho, inclusive uma recusa por teto, chega sempre pelo webhook.

{% hint style="warning" %}
**O evento é o mesmo, mas a causa é distinguível pelo `error.code`.** Uma recusa por teto e uma recusa da Caixa chegam as duas como `CONTRACT_ENDORSEMENT_REJECTED` — o que separa as duas é o `OperationError` do evento, que no corpo entregue ao seu endpoint fica em **`data.error`**:

```json
{ "eventType": "CONTRACT_ENDORSEMENT_REJECTED",
  "data": { "status": "ENDORSEMENT_REJECTED", "error": { "code": "ENDORSEMENT_RETRY_LIMIT_EXCEEDED" } } }
```

| `data.error.code`                             | Significado                                                                                                      |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `ENDORSEMENT_RETRY_LIMIT_EXCEEDED`            | acabaram as tentativas — **não** houve nova chamada à Caixa                                                      |
| `ENDORSEMENT_NOT_RETRYABLE`                   | a reserva não estava num estado retentável                                                                       |
| `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` | reserva anterior ao formato atual de períodos                                                                    |
| qualquer outro                                | a nova tentativa chegou à Caixa e foi recusada por ela — veja `data.error.originalErrors` para o código da Caixa |

Programe pelo `data.error.code`, não pelo `eventType`. Formato completo em [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md).
{% endhint %}

## Request

`POST /api/v1/fgts/contracts/{contractNumber}/endorsement-retries`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro         | Local  | Tipo                                                   | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | ------ | ------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contractNumber`  | path   | `string` (1 a 50 caracteres, `^[A-Za-z0-9._-]{1,50}$`) | Sim         | Número do contrato (CCB) a reprocessar — o mesmo valor devolvido na formalização, zero-padded em 8 dígitos (ex.: `00012345`). O endpoint aceita uma faixa mais ampla de caracteres na entrada, mas **só valor numérico é processado**: qualquer outro formato é rejeitado adiante com `400`. Apenas contratos do próprio originator são acessíveis. |
| `Idempotency-Key` | header | `string` (máx. 255)                                    | Não         | Chave de idempotência de negócio. Reenviar a mesma chave devolve o `requestId` existente sem reprocessar. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md).                                                                                                                                              |

### Corpo

**Não há corpo.** O `contractNumber` do path identifica o contrato, e a reserva a reprocessar é resolvida internamente — o `reserveIdentifier` é o mesmo da averbação original.

## Response

| Campo       | Tipo            | Descrição                                                                                                                |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `requestId` | `string` (uuid) | Identificador único **desta tentativa**, gerado pela API. Cada retentativa tem o seu — use para correlacionar o webhook. |
| `status`    | `string`        | `QUEUED` — pedido encaminhado para processamento assíncrono.                                                             |

* **202 Accepted** — pedido de retentativa encaminhado. **Não** confirma que a retentativa foi autorizada: uma recusa por teto ainda pode chegar depois, por webhook.

## Exemplo

```http
POST /api/v1/fgts/contracts/00012345/endorsement-retries HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Idempotency-Key: retry-endorsement-00012345-1
```

```json
{
  "requestId": "c3d4e5f6-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED"
}
```

## Próximo passo

Acompanhe o desfecho em [Consultar Contrato](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/consultar-contrato.md) — o contrato passa por `PENDING_ENDORSEMENT` e vai para `ENDORSED` ou volta para `ENDORSEMENT_REJECTED` — ou aguarde o callback no webhook cadastrado.

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `contractNumber` fora de `^[A-Za-z0-9._-]{1,50}$` — `errorCode = VALIDATION_ERROR`. Não-numérico ou com mais de 8 dígitos é recusado adiante, pelo serviço de formalização — `errorCode = CONTRACT_REQUEST_REJECTED`                                                                              |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                  |
| 404    | Contrato inexistente ou pertencente a outro originator — `errorCode = CONTRACT_NOT_FOUND`                                                                                                                                                                                                         |
| 409    | Contrato não está em `ENDORSEMENT_REJECTED` e por isso não admite retentativa — `errorCode = CONTRACT_INVALID_STATUS`                                                                                                                                                                             |
| 409    | Retentativa concorrente para o mesmo contrato — `errorCode = CONTRACT_REQUEST_REJECTED`                                                                                                                                                                                                           |
| 422    | `Idempotency-Key` já usada nesta rota para outro `contractNumber` — `errorCode = IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`. Nada é enfileirado; para uma operação nova, use uma chave nova. Ver [Idempotência](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/idempotencia.md#payload-diferente) |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                            |
| 503    | Serviço de formalização temporariamente indisponível — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE`. Aguarde os segundos do header `Retry-After` e repita com a **mesma** `Idempotency-Key`                                                                                                   |

Os erros seguem o formato `ProblemDetail` (RFC 7807), com o campo `errorCode`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

{% hint style="info" %}
**Não espere `409 ENDORSEMENT_RETRY_LIMIT_EXCEEDED` aqui.** Esse código existe apenas na [retentativa por reserva](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md). Nesta rota, o teto atingido devolve `202` e recusa por webhook.
{% endhint %}

## Reprocessa a averbação de um contrato recusado

> Solicita nova tentativa de averbação para um contrato em \`ENDORSEMENT\_REJECTED\`, reusando o mesmo \`reserveIdentifier\`. O contrato é resolvido pelo par (originador autenticado, \`contractNumber\`): contrato de outro originador responde \`404\`.\
> ⚠️ Diferente da rota \`POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries\`, \*\*a decisão sobre a retentativa não cabe nesta resposta\*\*: o \`202\` confirma apenas a admissão, e a recusa por teto não volta aqui como \`409\` — o \`409\` desta rota cobre os conflitos detectados na admissão, não o desfecho da retentativa. A recusa chega pelo webhook \`CONTRACT\_ENDORSEMENT\_REJECTED\` já existente — o mesmo evento emitido quando a Caixa recusa — \*\*e\*\* fica consultável em \`GET /api/v1/fgts/operations/{requestId}\`, que passa a responder \`200\` com \`status: FAILED\` e o \`error.code\` identificando a causa: \`ENDORSEMENT\_RETRY\_LIMIT\_EXCEEDED\` (teto de retentativas atingido), \`ENDORSEMENT\_NOT\_RETRYABLE\` (contrato não está num estado que permita reprocessar) ou \`ENDORSEMENT\_RETRY\_UNSUPPORTED\_LEGACY\_RECORD\` (reserva com payload em formato legado, não reprocessável por esta rota).\
> O header \`Idempotency-Key\` é aceito para deduplicação de negócio.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"fgts-contracts","description":"Submissão e acompanhamento de contratos (formalização) FGTS."}],"servers":[{"url":"https://ingress.gtfgts.staging.giro.tech","description":"Homologação (testes e validação da integração)"},{"url":"https://gtfgts.giro.tech","description":"Produção (operações reais)"},{"url":"http://localhost:8080","description":"Local (bootRun -Pprofiles=local)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints `/api/v1/**`.\nInclua no header: `Authorization: Bearer <token>`."}}},"paths":{"/api/v1/fgts/contracts/{contractNumber}/endorsement-retries":{"post":{"operationId":"submitContractEndorsementRetry","tags":["fgts-contracts"],"summary":"Reprocessa a averbação de um contrato recusado","description":"Solicita nova tentativa de averbação para um contrato em `ENDORSEMENT_REJECTED`, reusando o mesmo `reserveIdentifier`. O contrato é resolvido pelo par (originador autenticado, `contractNumber`): contrato de outro originador responde `404`.\n⚠️ Diferente da rota `POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`, **a decisão sobre a retentativa não cabe nesta resposta**: o `202` confirma apenas a admissão, e a recusa por teto não volta aqui como `409` — o `409` desta rota cobre os conflitos detectados na admissão, não o desfecho da retentativa. A recusa chega pelo webhook `CONTRACT_ENDORSEMENT_REJECTED` já existente — o mesmo evento emitido quando a Caixa recusa — **e** fica consultável em `GET /api/v1/fgts/operations/{requestId}`, que passa a responder `200` com `status: FAILED` e o `error.code` identificando a causa: `ENDORSEMENT_RETRY_LIMIT_EXCEEDED` (teto de retentativas atingido), `ENDORSEMENT_NOT_RETRYABLE` (contrato não está num estado que permita reprocessar) ou `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` (reserva com payload em formato legado, não reprocessável por esta rota).\nO header `Idempotency-Key` é aceito para deduplicação de negócio.","parameters":[{"name":"contractNumber","in":"path","required":true,"description":"Número do contrato (CCB) a reprocessar.","schema":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._-]{1,50}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Chave de idempotência de negócio. Reenviar a mesma chave retorna o `requestId` existente sem reprocessar.","schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Retentativa admitida para processamento assíncrono. O `requestId` devolvido identifica esta tentativa ponta a ponta.","content":{"application/json":{"schema":{"type":"object","description":"Confirmação de admissão assíncrona da operação FGTS (`202 Accepted`). O processamento ocorre em background; acompanhe pelo `requestId` via polling (`GET /api/v1/fgts/operations/{requestId}`) ou pelo webhook cadastrado.\n**Exceção para `balance-queries`:** quando o saldo já está disponível, a resposta é `200 OK` com `status: COMPLETED`, `source: CAIXA_CALL` e `result` com o saldo — não é necessário polling, e o webhook é enviado também. Caso contrário, retorna `202`.","required":["requestId","status"],"properties":{"requestId":{"type":"string","format":"uuid","description":"Identificador único (UUID) gerado pelo serviço para esta chamada. Em resposta `202` a requisição foi admitida no processamento assíncrono e este é o identificador de polling: use-o em `GET /api/v1/fgts/operations/{requestId}`. Em resposta `200` de `balance-queries` o resultado já vem inline em `result`, e a operação também é admitida com este `requestId`: é o mesmo do webhook e é consultável em `GET /api/v1/fgts/operations/{requestId}`. Só é preciso fazer polling quando o `status` for `QUEUED`."},"status":{"type":"string","enum":["QUEUED","COMPLETED"],"description":"Status da operação no momento da admissão. `QUEUED`: operação enfileirada para processamento assíncrono (resposta `202`). `COMPLETED`: resultado disponível inline no campo `result` — ocorre apenas quando o saldo de `balance-queries` já está disponível (resposta `200`)."},"source":{"type":"string","nullable":true,"enum":["CAIXA_CALL"],"description":"Origem do resultado. Presente apenas em resposta `200` de `balance-queries`. `CAIXA_CALL`: saldo apurado na Caixa. Nulo em respostas `202`."},"result":{"nullable":true,"description":"Resultado da operação. Presente apenas em resposta `200` de `balance-queries`. Nulo em respostas `202`.","oneOf":[{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) com saldo disponível — saldo FGTS do trabalhador, com a lista de períodos e valores por competência.","required":["workerCpf","balanceDate"],"properties":{"workerCpf":{"type":"string","description":"CPF do trabalhador (11 dígitos, sem pontuação)."},"balanceDate":{"type":"string","format":"date","description":"Data de referência do saldo consultado (ISO-8601, ex. `2026-05-20`)."},"hasDisregardedBalance":{"type":"boolean","description":"Indica que o trabalhador possui valores de FGTS não considerados no saldo retornado, por não estarem disponíveis para uso como garantia. Pode vir ausente quando a Caixa não informa o campo."},"activeRequestCount":{"type":"integer","description":"Quantidade de pedidos de garantia ativos para o trabalhador na Caixa, considerando todas as instituições — não apenas as reservas deste originador. Reflete o momento da apuração do saldo, não o da requisição: o valor pode estar desatualizado."},"periods":{"type":"array","description":"Lista de períodos com valor disponível para averbação.","items":{"type":"object","description":"Período de competência com valor disponível para averbação.","required":["transferDate","amount"],"properties":{"transferDate":{"type":"string","format":"date","description":"Data de transferência (competência) do período (ISO-8601, ex. `2026-05-01`)."},"amount":{"type":"number","description":"Valor disponível para averbação neste período."}}}}}},{"type":"object","description":"Resultado de consulta de saldo (`BALANCE_QUERY`) sem saldo disponível para averbação.","required":["hasBalance"],"properties":{"hasBalance":{"type":"boolean","description":"Sempre `false` — indica ausência de saldo."}}}]},"reserveIdentifier":{"type":"string","nullable":true,"minLength":13,"maxLength":14,"pattern":"^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$","description":"Identificador determinístico de 13 ou 14 caracteres (`GTD{contractNumber:8}{code:2..3}`) gerado no momento da submissão de averbação — o código do originador tem 2 ou 3 caracteres. Presente apenas em respostas `202` de `POST /endorsements`. Nulo para todos os outros tipos de operação."}}}}}},"400":{"description":"Requisição inválida — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo `errors` contém um mapa `{ \"campo\": \"mensagem\" }` para cada campo inválido. O campo `title` é sempre `\"Bean validation error\"` e `detail` é sempre `\"One or more fields were invalid. See 'errors' for details.\"`.\nRejeições de regra de negócio também chegam como `400`, com `errorCode` próprio (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Quando a rejeição aponta um campo do request, ela traz o mesmo `errors` e o mesmo `detail`; quando não há campo associado, `errors` é omitido e `detail` é o reason phrase do status.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"401":{"description":"Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header `Authorization: Bearer <token>`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"404":{"description":"Recurso não encontrado — identificador inexistente ou ainda não processado.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"409":{"description":"Conflito com o estado atual do recurso — o pedido é válido, mas não cabe no estado em que o recurso está. O caso específico vem no `errorCode` do corpo; a descrição de cada rota lista os códigos que ela pode devolver.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"500":{"description":"Erro interno inesperado no servidor.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"503":{"description":"Serviço temporariamente indisponível. Aguarde `Retry-After` segundos e tente novamente.","headers":{"Retry-After":{"description":"Segundos recomendados até a próxima tentativa.","schema":{"type":"integer","format":"int64"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}}}}}}}
```

## Resultado no webhook

**A retentativa não emite evento próprio.** O que chega ao webhook cadastrado (`source = CONTRACT`) é o desfecho da **nova tentativa de averbação**, nos mesmos eventos de sempre:

| `eventType`                     | Quando                                                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `CONTRACT_ENDORSED`             | a nova tentativa foi averbada com sucesso (contrato em `ENDORSED`) — a formalização segue normalmente             |
| `CONTRACT_ENDORSEMENT_REJECTED` | a nova tentativa foi recusada, **ou** o teto de tentativas foi atingido (contrato volta a `ENDORSEMENT_REJECTED`) |

A trilha que chega ao seu webhook é, portanto: **recusa → silêncio → desfecho da nova tentativa**. A volta do contrato para `PENDING_ENDORSEMENT` **não** gera evento; o silêncio entre a recusa e o próximo evento é **esperado** e não deve ser tratado como evento perdido.

Catálogo completo em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md) e [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md). Ciclo de vida completo em [Fluxo de formalização](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-formalizacao.md).

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