> 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/operacoes-fgts/submeter-operacoes/retentar-averbacao.md).

# Retentativa de Averbação por identificador

{% hint style="warning" %}
**Tem um contrato?** Prefira [`POST /api/v1/fgts/contracts/{contractNumber}/endorsement-retries`](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/contratos/retentar-averbacao.md): o `contractNumber` já identifica a reserva, e você não precisa guardar o `reserveIdentifier`.

Este endpoint permanece disponível para retentar a averbação de uma reserva **avulsa** — averbada sem contrato associado na Giro —, quando o `reserveIdentifier` é a única referência que você tem.
{% endhint %}

Solicita uma **nova tentativa de averbação** para uma reserva cuja averbação foi recusada. A retentativa **reusa o mesmo `reserveIdentifier`** — que é a chave da reserva junto à Caixa —, portanto **não nasce reserva nova** e nada muda nos períodos já informados na averbação original.

{% hint style="info" %}
Esta operação é **assíncrona**: a resposta `202` confirma apenas a admissão da nova tentativa. O resultado chega depois via [webhook](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) ou por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) do `requestId` devolvido.
{% endhint %}

## Quando usar

Depois de receber um `ENDORSEMENT_FAILED` no webhook (ou um `status = FAILED` no polling) para uma averbação.

**Um `ENDORSEMENT_NEEDS_VERIFICATION` também é retentável.** Esse evento (`status = EXPIRED`) diz que a averbação terminou **sem veredito da Caixa** — ninguém negou nada, a operação apenas não se resolveu a tempo. A reserva fica num estado de falha como qualquer outro, e a retentativa é admitida normalmente. Antes de pedir, confirme o desfecho por [polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md): se ele tiver se resolvido sozinho no intervalo, não há o que retentar.

**Você não precisa classificar o erro da Caixa para decidir.** Não existe taxonomia que separe falhas "retentáveis" de "terminais": se a averbação chegou à Caixa e foi recusada — seja negativa de negócio, seja falha sem veredito —, ela é retentável enquanto houver tentativa disponível.

O que muda essa conclusão são as falhas que **não chegaram à Caixa**, listadas logo abaixo. Se você prefere uma regra única: tente a retentativa e trate o `409` — a API responde na hora se o caso não for elegível.

O que **não** é retentável:

| Situação                                                                            | Resposta                                          |
| ----------------------------------------------------------------------------------- | ------------------------------------------------- |
| Reserva que não está em falha — em processamento, já averbada, quitada ou cancelada | `409 ENDORSEMENT_NOT_RETRYABLE`                   |
| Averbação recusada **antes** de chegar à Caixa por `reserveIdentifier` duplicado    | `409 ENDORSEMENT_NOT_RETRYABLE`                   |
| Reserva anterior ao formato atual de períodos                                       | `409 ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` |
| `reserveIdentifier` inexistente para o seu originador                               | `404 GUARANTEE_NOT_FOUND`                         |

A duplicidade fica de fora de propósito: a averbação nunca chegou à Caixa, e uma retentativa colidiria de novo — gastaria as tentativas contra algo que não pode dar certo. Nesse caso o caminho é submeter uma averbação nova, com outro `contractNumber`.

## Antes de retentar, a Giro já retentou <a href="#antes-de-retentar" id="antes-de-retentar"></a>

Quando a Caixa responde um **erro transitório** — serviço indisponível, ou um pedido explícito de nova tentativa —, a averbação **não falha na hora**. A Giro reenfileira a operação e tenta de novo **a cada 15 minutos, por até 72 horas**, antes de declarar falha.

Cada ciclo começa por uma **consulta pelo `reserveIdentifier`**: se a averbação tiver se efetivado na Caixa nesse intervalo, o resultado é resolvido pelo protocolo encontrado e nada é reenviado. Só há novo envio quando a consulta confirma que nada foi efetivado — e sempre reusando o **mesmo `reserveIdentifier`**, de modo que não nasce reserva nova em nenhum ciclo.

Duas consequências práticas para a sua integração:

* **Uma averbação pode ficar em andamento por até 72 horas sem gerar evento.** O silêncio é esperado. Não trate como operação perdida e não programe timeout curto — ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).
* **Quando o `ENDORSEMENT_FAILED` chega, a insistência já aconteceu.** Não faz sentido retentar imediatamente "porque pode ter sido instabilidade": esse cenário já foi esgotado antes de o evento sair.

Falhas que a Caixa **julgou** — averbação negada — não passam por essa janela. Elas falham na primeira resposta, porque insistir não mudaria o resultado.

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

Nesta rota a recusa por teto volta **de forma síncrona, na própria resposta**: `409` com `errorCode = ENDORSEMENT_RETRY_LIMIT_EXCEEDED`. Você sabe na hora que acabaram as tentativas, sem precisar esperar webhook.

**Cada retentativa abre a sua própria janela de 72 horas.** Ela é uma tentativa de negócio nova, não a continuação da anterior: se voltar a esbarrar em erro transitório, ganha 72 horas próprias de insistência a cada 15 minutos.

| Tentativa                          | Janela automática       |
| ---------------------------------- | ----------------------- |
| Averbação original                 | até 72 h                |
| Retentativa 1                      | até 72 h                |
| Retentativa 2                      | até 72 h                |
| Retentativa 3                      | até 72 h                |
| **Total até a reserva se esgotar** | **até 288 h — 12 dias** |

Esse é o teto do **caso patológico**: Caixa indisponível por dias seguidos e você retentando as três vezes. O caminho comum termina no primeiro ciclo. Mas se a sua operação tem prazo contratual ou trava de conciliação amarrada à averbação, **12 dias é o número a considerar, não 72 horas**.

{% 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 %}

## Request

`POST /api/v1/fgts/endorsements/{reserveIdentifier}/retries`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro           | Local  | Tipo                                                                      | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ------ | ------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reserveIdentifier` | path   | `string` (13 ou 14 caracteres, `^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$`) | Sim         | Identificador da reserva a reprocessar — exatamente o valor devolvido no `202` da [averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md). Tem **13 ou 14 caracteres**: o código do originador no final é de 2 ou 3 caracteres (ex.: `GTD00000042AB` e `GTD00000042GV8` são ambos válidos). |
| `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.** Toda a informação necessária está no `reserveIdentifier` do path: a nova tentativa reusa CPF, tipo de operação e períodos 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 no polling em `GET /api/v1/fgts/operations/{requestId}` e para correlacionar o webhook. |
| `status`    | `string`        | `QUEUED` — retentativa enfileirada para processamento assíncrono.                                                                                                                  |

* **202 Accepted** — retentativa admitida e slot consumido. Quando concluída, o `result` do polling conterá um protocolo gerado pela Caixa.

{% hint style="info" %}
O `reserveIdentifier` **não** é repetido na resposta: ele já é o que você enviou no path, e continua sendo o mesmo entre todas as tentativas.
{% endhint %}

## Exemplo

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

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

### Teto atingido (409)

```json
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "The guarantee service rejected this request.",
  "errorCode": "ENDORSEMENT_RETRY_LIMIT_EXCEEDED",
  "timestamp": "2026-08-14T12:00:00Z"
}
```

## Próximo passo

Acompanhe o resultado em [Consultar status da operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/acompanhar-resultado/consultar-status-operacao.md) usando o `requestId` retornado, ou aguarde o callback no webhook cadastrado.

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `reserveIdentifier` fora do padrão `^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$` ou com tamanho diferente de 13/14 caracteres — `errorCode = VALIDATION_ERROR`                                                                                                                                               |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                         |
| 404    | Reserva inexistente ou pertencente a outro originator — `errorCode = GUARANTEE_NOT_FOUND`                                                                                                                                                                                                                |
| 409    | Teto de tentativas atingido (3 retentativas) — `errorCode = ENDORSEMENT_RETRY_LIMIT_EXCEEDED`                                                                                                                                                                                                            |
| 409    | A reserva não está num estado de falha e por isso não admite retentativa (em processamento — inclusive durante a [retentativa automática](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#retrying) —, já averbada, quitada, cancelada, etc.) — `errorCode = ENDORSEMENT_NOT_RETRYABLE` |
| 409    | A reserva foi criada num formato de registro antigo que a retentativa não consegue reprocessar — `errorCode = ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD`. Abra chamado no [suporte](https://giro.tech/central-de-atendimento/)                                                                         |
| 422    | `Idempotency-Key` já usada nesta rota para outro `reserveIdentifier` — `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)     |
| 4xx    | A plataforma não conseguiu concluir a retentativa — `errorCode = GUARANTEE_LEDGER_CLIENT_ERROR`. Acione o suporte                                                                                                                                                                                        |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                                   |
| 503    | Serviço temporariamente indisponível — `errorCode = GUARANTEE_LEDGER_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`. Os `409` desta rota saem sem `type`, `instance` e `message` — leia o `errorCode`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

{% hint style="info" %}
Uma recusa `409` **não consome** tentativa: o contador só avança quando a retentativa é admitida (`202`).
{% endhint %}

## Reprocessa uma averbação recusada

> Solicita nova tentativa de averbação para uma reserva já existente, reusando o mesmo \`reserveIdentifier\`. O contador de tentativas e o teto são verificados de forma síncrona por esta rota: quando o teto estoura a recusa volta \*\*nesta mesma resposta\*\*, como \`409 ENDORSEMENT\_RETRY\_LIMIT\_EXCEEDED\`.\
> 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-operations","description":"Submissão assíncrona de operações FGTS (balance-queries, endorsements, guarantee-maintenances, reserve-cancellations, reserve-value-queries, reserve-protocol-queries, protocol-status-queries), polling de status por `requestId` e cancelamento síncrono de operação. Todas protegidas por JWT do originator."}],"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/endorsements/{reserveIdentifier}/retries":{"post":{"operationId":"retryEndorsement","tags":["fgts-operations"],"summary":"Reprocessa uma averbação recusada","description":"Solicita nova tentativa de averbação para uma reserva já existente, reusando o mesmo `reserveIdentifier`. O contador de tentativas e o teto são verificados de forma síncrona por esta rota: quando o teto estoura a recusa volta **nesta mesma resposta**, como `409 ENDORSEMENT_RETRY_LIMIT_EXCEEDED`.\nO header `Idempotency-Key` é aceito para deduplicação de negócio.","parameters":[{"name":"reserveIdentifier","in":"path","required":true,"description":"Identificador determinístico da reserva a reprocessar.","schema":{"type":"string","minLength":13,"maxLength":14,"pattern":"^GT[FD][0-9]{8}[0-9A-HJKMNP-TV-Z]{2,3}$"}},{"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. O `requestId` devolvido é o identificador desta tentativa, permitindo correlacionar o resultado ponta a ponta em `GET /api/v1/fgts/operations/{requestId}`.","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":"`ENDORSEMENT_RETRY_LIMIT_EXCEEDED` — o teto de retentativas da reserva foi atingido; ou `ENDORSEMENT_NOT_RETRYABLE` — a garantia não está num estado de falha, então não há o que reprocessar; ou `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` — a reserva tem payload em formato legado e não é reprocessável por esta rota; entre em contato com o suporte. O código vem em `errorCode`.","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 de garantias indisponível (`GUARANTEE_LEDGER_UNAVAILABLE`). Aguarde `Retry-After` — 60 s em indisponibilidade, 5 s em sobrecarga — e repita com a mesma `Idempotency-Key`.","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 você recebe é o desfecho da **nova tentativa de averbação**, nos mesmos eventos de sempre (`source = ENDORSEMENT`):

| `eventType`                      | Quando                                                                                                                                                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ENDORSEMENT_COMPLETED`          | a nova tentativa foi averbada com sucesso                                                                                                                          |
| `ENDORSEMENT_FAILED`             | a nova tentativa também foi recusada                                                                                                                               |
| `ENDORSEMENT_NEEDS_VERIFICATION` | a nova tentativa expirou sem desfecho — verifique por polling antes de assumir o desfecho. A reserva **continua retentável**, se ainda houver tentativa disponível |

A trilha que chega ao seu webhook é, portanto: **recusa → silêncio → desfecho da nova tentativa**. O silêncio entre a recusa e o próximo evento é **esperado** — a admissão da retentativa (`202`) não gera callback. Não o trate como evento perdido.

Correlacione pelo `requestId`: cada tentativa tem o seu, e é ele que viaja no `data.requestId` do evento. O `data.reserveIdentifier` é o mesmo em todas as tentativas.

Formato dos payloads em [Averbação (Legado)](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/submeter-averbacao.md#resultado-no-webhook), 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).

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