> 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/acompanhar-resultado/consultar-status-operacao.md).

# Consultar Status da Operação

Retorna o status atual e o resultado (quando disponível) de uma operação FGTS identificada pelo `requestId` retornado na admissão (`202`). Use este endpoint para **polling** quando não usar webhook.

{% hint style="info" %}
Apenas o originator dono da operação pode consultá-la. O enum de status inclui estados que podem exigir intervenção manual (`NEEDS_VERIFICATION`, `FAILED_NEEDS_MANUAL`). Ver [Fluxo assíncrono e polling](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/fluxo-assincrono-e-polling.md).
{% endhint %}

## Request

`GET /api/v1/fgts/operations/{requestId}`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro   | Local | Tipo            | Obrigatório | Descrição                                                                                                                     |
| ----------- | ----- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `requestId` | path  | `string` (uuid) | Sim         | Identificador único da operação retornado na admissão (`202`). Formato UUID v4 (ex.: `f47ac10b-58cc-4372-a567-0e02b2c3d479`). |

## Response

| Campo                  | Tipo                        | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId`            | `string`                    | Identificador único da requisição (UUID gerado pela API).                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `status`               | `string`                    | Status atual da operação no processamento. Enum: `QUEUED`, `DISPATCHING`, `IN_FLIGHT`, `AWAITING_PROVIDER`, `NEEDS_VERIFICATION`, `RETRYING`, `PENDING_MANUAL_APPROVAL`, `COMPLETED`, `FAILED`, `FAILED_NEEDS_MANUAL`, `EXPIRED`, `CANCELLED`. `PENDING_MANUAL_APPROVAL` indica cancelamento de reserva ou manutenção de garantia retido para revisão manual antes do envio à Caixa. Significado e ação de cada valor em [Status da operação](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-status). |
| `source`               | `string`                    | Origem do resultado quando `status = COMPLETED`: `CAIXA_CALL` (saldo apurado na Caixa) ou `NA`. Pode ser `null`.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `result`               | `object`                    | Resultado da operação — presente **apenas** em `COMPLETED`. A forma varia por tipo de operação (ver abaixo). Pode ser `null`.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `error`                | `object` (`OperationError`) | Erro da operação — presente em `FAILED`, `FAILED_NEEDS_MANUAL` e `EXPIRED`, e também em `NEEDS_VERIFICATION`, onde descreve a verificação em curso e não um desfecho. `null` em `QUEUED`, `COMPLETED` e `CANCELLED`. Catálogo de `error.code` em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#catalogo-operacao).                                                                                                                                                                             |
| `estimatedWaitSeconds` | `integer`                   | Estimativa best-effort de segundos até a conclusão (não é garantia). `null` em estados terminais ou quando indisponível.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `reserveIdentifier`    | `string`                    | Identificador da reserva associada à operação, quando aplicável (`ENDORSEMENT`, `CANCEL_RESERVE`, `MAINTAIN_GUARANTEE`) e conhecido — o mesmo valor entregue nos eventos de webhook. Use-o para retentar a averbação, cancelar ou consultar a garantia. `null` para operações sem reserva associada.                                                                                                                                                                                                                             |
| `retry`                | `object` (`RetryProgress`)  | Progresso da janela de retentativa automática — presente **apenas** enquanto `status = RETRYING`. Ver detalhamento abaixo. `null` fora da janela.                                                                                                                                                                                                                                                                                                                                                                                |

### Formas de `result` (por tipo de operação)

* **Averbação / manutenção de garantia / cancelamento de reserva** → protocolo: `protocolNumber`, `protocolStatus`, `detail`.
* **Consulta de valor reservado** → reserva atualizada: `reserveIdentifier`, `periods[]` (`periodStatus`, `transferDate`, `originalAmount`, `updatedAmount`).
* **Consulta de protocolos por reserva** → lista de protocolos: `protocols[]` (`protocolNumber`, `protocolStatus`).
* **Consulta de saldo** → objeto livre com o saldo.

### Campo `error` (`OperationError`)

| Campo               | Tipo     | Descrição                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`              | `string` | Código de erro canônico estável da API (não é o código cru da Caixa).                                                                                                                                                                                                                                                                                                     |
| `message`           | `string` | Mensagem legível em português descrevendo o erro.                                                                                                                                                                                                                                                                                                                         |
| `originalErrors`    | `array`  | Erros crus do provedor (Caixa) — presente **apenas** quando houve chamada à Caixa com erro. Cada item: `provider`, `code`, `description`, `httpStatus`, `requestIdentifier`, `occurredAt`. Pode ser `null`.                                                                                                                                                               |
| `originalRequestId` | `string` | Presente **apenas** quando `code` ∈ {`ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE`, `GUARANTEE_APPROVAL_ALREADY_PENDING`}: o `requestId` da operação que de fato está em andamento (ou concluída). Consulte-o para acompanhar o desfecho real. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#originalrequestid). |

### Campo `retry` (`RetryProgress`)

Presente **apenas** enquanto `status = RETRYING`. A Caixa devolveu um código transitório e a mesma reserva é reenviada automaticamente a cada 15 minutos, por até 72 horas.

| Campo               | Tipo                 | Descrição                                                                                                                                                                                                                   |
| ------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `providerAttempt`   | `integer`            | Tentativas automáticas **nossas** já feitas nesta janela. **Não** é o seu orçamento de retentativas manuais, que é de 3 por reserva.                                                                                        |
| `nextAttemptAt`     | `string` (date-time) | Quando será a próxima tentativa automática.                                                                                                                                                                                 |
| `windowExpiresAt`   | `string` (date-time) | Fim da janela. Depois disso a operação encerra com `error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED` e a retentativa manual passa a ser aceita.                                                                             |
| `eligible`          | `boolean`            | Sempre `false` durante a janela: [Retentar averbação](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/operacoes-fgts/submeter-operacoes/retentar-averbacao.md) responderia `409 ENDORSEMENT_NOT_RETRYABLE`. |
| `lastProviderError` | `object`             | O que a Caixa respondeu na tentativa que colocou a operação na janela. Mesma forma de um item de `error.originalErrors`: `provider`, `code`, `description`, `httpStatus`, `requestIdentifier`. Pode ser `null`.             |

{% hint style="warning" %}
**`error` é `null` durante a janela — e isso é intencional.** A operação **não falhou**: ela ainda será tentada. O motivo da espera fica em `retry.lastProviderError`, justamente para que um cliente em polling não leia "em andamento" como "falhou".

É esse campo que diz se há algo a fazer. O código **`7`** (`httpStatus 403`) significa que o trabalhador ainda não autorizou a operação no app do FGTS: **peça a ele que autorize** e a próxima tentativa converte — a mediana observada é de 4 a 5 tentativas, cerca de 75 minutos. Já os códigos **`3`**, **`14`** e **`524`** são instabilidade da Caixa: não há ação do seu lado além de aguardar a janela.
{% endhint %}

* **200 OK** — status atual da operação (em qualquer estado do enum).

{% hint style="info" %}
**Recusas são consultáveis.** Uma operação recusada na admissão do processamento — averbação duplicada, recusa no gate de cancelamento/manutenção (garantia inexistente, fora de estado elegível, aprovação já pendente, operação inválida) — responde `200` com `status = FAILED` já na **primeira consulta**, com o **mesmo `error.code`** do evento `FAILED` entregue por webhook (ex.: `GUARANTEE_NOT_FOUND`, `GUARANTEE_NOT_GATEABLE`, `GUARANTEE_ALREADY_CANCELLED`, `GUARANTEE_APPROVAL_ALREADY_PENDING`, `GUARANTEE_OPERATION_DUPLICATE`, `ENDORSEMENT_ALREADY_SUBMITTED`). O `404` significa apenas `requestId` inexistente — não o trate como "ainda processando" nem como sinal de recusa; programe pelo `error.code`.
{% endhint %}

## Exemplo

### Em processamento — `QUEUED`

```http
GET /api/v1/fgts/operations/f47ac10b-58cc-4372-a567-0e02b2c3d479 HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
```

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "QUEUED",
  "source": "NA",
  "estimatedWaitSeconds": 18
}
```

### Concluída — `COMPLETED` (averbação)

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "COMPLETED",
  "source": "CAIXA_CALL",
  "reserveIdentifier": "GTD00000042AB",
  "result": {
    "protocolNumber": "123456789",
    "protocolStatus": "ENDORSED",
    "detail": { "href": "/fgts/v1/protocolos/123456789", "rel": "self" }
  }
}
```

### Em janela de retentativa — `RETRYING` (autorização pendente do trabalhador)

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "RETRYING",
  "source": "CAIXA_CALL",
  "reserveIdentifier": "GTD00000042AB",
  "result": null,
  "error": null,
  "retry": {
    "providerAttempt": 5,
    "nextAttemptAt": "2026-08-24T19:53:55Z",
    "windowExpiresAt": "2026-08-26T22:48:00Z",
    "eligible": false,
    "lastProviderError": {
      "provider": "CAIXA",
      "code": "7",
      "description": "Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária",
      "httpStatus": 403,
      "requestIdentifier": "GTD00000042AB"
    }
  }
}
```

Repare que `error` é `null`: a averbação está viva. Neste caso — código `7` — a ação é do trabalhador, no app do FGTS; assim que ele autorizar, a próxima tentativa automática conclui a operação sem que você precise reenviar nada.

### Falhada — `FAILED` (erro da Caixa repassado)

```json
{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "FAILED",
  "source": "CAIXA_CALL",
  "error": {
    "code": "ENDORSEMENT_DENIED",
    "message": "Averbação negada pelo provedor Caixa",
    "originalErrors": [
      {
        "provider": "CAIXA",
        "code": "14",
        "description": "Trabalhador não possui saldo suficiente",
        "httpStatus": 422,
        "requestIdentifier": "RES-20240901-001",
        "occurredAt": "2026-06-14T12:00:03Z"
      }
    ]
  }
}
```

### Recusada — `FAILED` com `originalRequestId` (averbação duplicada)

Recusa na admissão do processamento: resposta `200` com `status = FAILED` já na primeira consulta, sem `originalErrors[]` (a Caixa não foi chamada). O `error.originalRequestId` aponta a operação original — acompanhe o desfecho real por ele.

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef0987654321",
  "status": "FAILED",
  "source": "NA",
  "reserveIdentifier": "GTD00000042AB",
  "error": {
    "code": "ENDORSEMENT_ALREADY_SUBMITTED",
    "message": "Averbação já submetida para esta reserva",
    "originalRequestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}
```

## Erros

| Código | Situação                                                                                                                                                                                                                                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | `requestId` não é um UUID — `errorCode = VALIDATION_ERROR`                                                                                                                                                                                                                                                         |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                                                                                                                                                                                                   |
| 403    | A operação não pertence ao originator autenticado (acesso cruzado) — `errorCode = ORIGINATOR_OWNERSHIP_VIOLATION`                                                                                                                                                                                                  |
| 404    | `requestId` inexistente ou ainda não registrado — `errorCode = OPERATION_NOT_FOUND`. Logo após o `202` de averbação, cancelamento ou manutenção, o `404` pode durar alguns segundos; consulte de novo antes de concluir. Operação **recusada** não retorna `404`: responde `200` com `status = FAILED` (ver acima) |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                                                                                                                                                                                                             |
| 4xx    | A plataforma não conseguiu concluir a consulta — `errorCode = GUARANTEE_LEDGER_CLIENT_ERROR`. Um `401`/`403` com este código não se refere ao seu token. Acione o suporte com o `requestId`                                                                                                                        |
| 503    | Serviço temporariamente indisponível. Aguarde `Retry-After` segundos (`30`) — `errorCode = DISPATCHER_UNAVAILABLE`                                                                                                                                                                                                 |
| 503    | Indisponibilidade temporária na consulta de averbação, cancelamento de reserva ou manutenção de garantia — `errorCode = GUARANTEE_LEDGER_UNAVAILABLE`. Aguarde `Retry-After`                                                                                                                                       |

Estes 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).

A falha da **operação** em si (quando `status` ∈ {`FAILED`, `FAILED_NEEDS_MANUAL`, `EXPIRED`}) **não** é um `ProblemDetail`: vem no campo `error` da resposta `200` como um `OperationError` (`code`, `message`, `originalErrors[]`). Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

## Consulta o status de uma operação FGTS por requestId (polling)

> Retorna o status atual e o resultado (quando disponível) de uma operação FGTS identificada pelo \`requestId\` retornado na admissão (\`202\`).\
> \*\*Escopo por originator:\*\* apenas o originator dono da operação pode consultá-la. Acesso cruzado resulta em \`403\`.\
> \*\*Status completo:\*\* o enum de status inclui \`CANCELLED\`, \`NEEDS\_VERIFICATION\`, \`FAILED\_NEEDS\_MANUAL\` e \`PENDING\_MANUAL\_APPROVAL\` (que podem exigir intervenção manual). \`PENDING\_MANUAL\_APPROVAL\`: estado intermediário das operações retidas no gate de aprovação manual — \`CANCEL\_RESERVE\` e \`MAINTAIN\_GUARANTEE\` — antes do envio à Caixa; não é terminal. O webhook \`CANCEL\_RESERVE\_UNDER\_REVIEW\` é emitido pelo serviço \`fgts-webhook\` neste estado. Rejeitada a aprovação, a operação passa a \`FAILED\` com \`error.code = GUARANTEE\_APPROVAL\_REJECTED\` — o mesmo código do webhook, para que polling e webhook não se contradigam. Recusada na entrada do gate — garantia inexistente, fora de estado elegível, gate já pendente ou operação inválida — a operação nunca chega a \`PENDING\_MANUAL\_APPROVAL\`: responde \`FAILED\` já na primeira consulta, com o mesmo \`error.code\` do evento \`FAILED\` entregue por webhook. \`GUARANTEE\_OPERATION\_DUPLICATE\` indica submissão absorvida por uma operação já em andamento sob a mesma \`Idempotency-Key\` — acompanhe o \`requestId\` original. Programe pelo \`error.code\`; o \`error.message\` é texto de apresentação.\
> \*\*Campo \`error\`:\*\* presente apenas quando \`status\` ∈ {\`FAILED\`, \`FAILED\_NEEDS\_MANUAL\`, \`EXPIRED\`}. Contém o código canônico GTLab e, quando aplicável, os erros originais retornados pelo provedor. Distinto dos erros de validação e autenticação (\`400\`/\`401\`/\`403\`), que usam \`ProblemDetail\`.\
> \*\*\`estimatedWaitSeconds\`:\*\* estimativa best-effort de conclusão; não é garantia de prazo.\
> \*\*Indisponibilidade temporária:\*\* \`503 Retry-After\`.

```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/operations/{requestId}":{"get":{"operationId":"getOperationStatus","tags":["fgts-operations"],"summary":"Consulta o status de uma operação FGTS por requestId (polling)","description":"Retorna o status atual e o resultado (quando disponível) de uma operação FGTS identificada pelo `requestId` retornado na admissão (`202`).\n**Escopo por originator:** apenas o originator dono da operação pode consultá-la. Acesso cruzado resulta em `403`.\n**Status completo:** o enum de status inclui `CANCELLED`, `NEEDS_VERIFICATION`, `FAILED_NEEDS_MANUAL` e `PENDING_MANUAL_APPROVAL` (que podem exigir intervenção manual). `PENDING_MANUAL_APPROVAL`: estado intermediário das operações retidas no gate de aprovação manual — `CANCEL_RESERVE` e `MAINTAIN_GUARANTEE` — antes do envio à Caixa; não é terminal. O webhook `CANCEL_RESERVE_UNDER_REVIEW` é emitido pelo serviço `fgts-webhook` neste estado. Rejeitada a aprovação, a operação passa a `FAILED` com `error.code = GUARANTEE_APPROVAL_REJECTED` — o mesmo código do webhook, para que polling e webhook não se contradigam. Recusada na entrada do gate — garantia inexistente, fora de estado elegível, gate já pendente ou operação inválida — a operação nunca chega a `PENDING_MANUAL_APPROVAL`: responde `FAILED` já na primeira consulta, com o mesmo `error.code` do evento `FAILED` entregue por webhook. `GUARANTEE_OPERATION_DUPLICATE` indica submissão absorvida por uma operação já em andamento sob a mesma `Idempotency-Key` — acompanhe o `requestId` original. Programe pelo `error.code`; o `error.message` é texto de apresentação.\n**Campo `error`:** presente apenas quando `status` ∈ {`FAILED`, `FAILED_NEEDS_MANUAL`, `EXPIRED`}. Contém o código canônico GTLab e, quando aplicável, os erros originais retornados pelo provedor. Distinto dos erros de validação e autenticação (`400`/`401`/`403`), que usam `ProblemDetail`.\n**`estimatedWaitSeconds`:** estimativa best-effort de conclusão; não é garantia de prazo.\n**Indisponibilidade temporária:** `503 Retry-After`.","responses":{"200":{"description":"Status atual da operação FGTS.","content":{"application/json":{"schema":{"type":"object","description":"Status corrente de uma operação FGTS, retornado por `GET /api/v1/fgts/operations/{requestId}`. O campo `error` está presente quando `status` ∈ {`FAILED`, `FAILED_NEEDS_MANUAL`, `EXPIRED`}, e também em `NEEDS_VERIFICATION`, onde descreve a verificação em curso e não um desfecho. O campo `result` só está presente quando `status` = `COMPLETED`. O estado `PENDING_MANUAL_APPROVAL` é intermediário e vale para as operações retidas no gate de aprovação manual (`CANCEL_RESERVE` e `MAINTAIN_GUARANTEE`) antes do envio à Caixa; o webhook `CANCEL_RESERVE_UNDER_REVIEW` é emitido neste estado. Rejeitada a aprovação, o status passa a `FAILED` com `error.code = GUARANTEE_APPROVAL_REJECTED`. Recusada na entrada do gate — garantia inexistente, fora de estado elegível, gate já pendente ou operação inválida —, ou recusada uma retentativa de averbação, a operação nunca chega a `PENDING_MANUAL_APPROVAL`: responde `FAILED` já na primeira consulta, com o mesmo `error.code` do evento `FAILED` entregue por webhook: `GUARANTEE_NOT_FOUND`, `GUARANTEE_REFERENCE_MISSING`, `GUARANTEE_NOT_GATEABLE`, `GUARANTEE_ALREADY_CANCELLED`, `GUARANTEE_APPROVAL_ALREADY_PENDING`, `GUARANTEE_OPERATION_DUPLICATE`, `INSTALLMENT_NOT_FOUND`, `INVALID_ADJUSTMENT_AMOUNT`, `ADJUSTMENT_EXCEEDS_RESIDUAL_AMOUNT`, `ENDORSEMENT_ALREADY_SUBMITTED`, `ENDORSEMENT_RETRY_LIMIT_EXCEEDED`, `ENDORSEMENT_NOT_RETRYABLE`, `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` e `GUARANTEE_OPERATION_REFUSED` (fallback quando o ledger não informa um código mais específico). `GUARANTEE_OPERATION_DUPLICATE` indica que a submissão foi absorvida por uma operação já em andamento com a mesma `Idempotency-Key` — o resultado sai no `requestId` original, não neste; esse `requestId` vem em `error.originalRequestId`. `GUARANTEE_APPROVAL_ALREADY_PENDING` indica que já existe uma operação desta garantia aguardando aprovação manual — o `requestId` dessa operação pendente também vem em `error.originalRequestId`. `ENDORSEMENT_ALREADY_SUBMITTED` indica que esta averbação já foi enviada antes — o `requestId` da submissão que de fato virou garantia vem em `error.originalRequestId`. Já em `ENDORSEMENT_RETRY_LIMIT_EXCEEDED`, `ENDORSEMENT_NOT_RETRYABLE` e `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD` esta própria operação já é o desfecho terminal — `error.originalRequestId`, quando presente, é apenas correlação com o `requestId` da averbação original da reserva, não uma indicação de que o desfecho real está em outro lugar. Programe sempre pelo `error.code`: o `error.message` é texto de apresentação e pode mudar sem aviso.","required":["requestId","status"],"properties":{"requestId":{"type":"string","description":"Identificador único da requisição (UUID)."},"status":{"type":"string","enum":["QUEUED","DISPATCHING","IN_FLIGHT","NEEDS_VERIFICATION","COMPLETED","FAILED","FAILED_NEEDS_MANUAL","EXPIRED","RETRYING","AWAITING_PROVIDER","CANCELLED","PENDING_MANUAL_APPROVAL"],"description":"Status atual da operação. Retorna o status completo da operação, incluindo estados intermediários como `NEEDS_VERIFICATION`, `FAILED_NEEDS_MANUAL` e `PENDING_MANUAL_APPROVAL` que podem exigir intervenção manual. `PENDING_MANUAL_APPROVAL`: cancelamento de reserva (`CANCEL_RESERVE`) ou manutenção de garantia (`MAINTAIN_GUARANTEE`) retido aguardando aprovação manual antes do envio à Caixa; não é terminal. `AWAITING_PROVIDER`: averbação aceita pela Caixa e ainda em processamento do lado dela; não é terminal, não reenvie. Significado e ação de cada valor em https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#catalogo-status"},"source":{"type":"string","enum":["CAIXA_CALL","NA"],"nullable":true,"description":"Origem do resultado quando `status = COMPLETED`. Presente e não-nulo apenas em terminal. `CAIXA_CALL`: resultado obtido via consulta ao provedor. `NA`: não aplicável ou ainda não determinado."},"result":{"nullable":true,"description":"Resultado da operação quando `status = COMPLETED`. A forma varia por `operationType`: `ENDORSE` / `MAINTAIN_GUARANTEE` / `CANCEL_RESERVE` → `ProtocolResult`; `QUERY_RESERVED_VALUE` → `ReservedValueResult`; `LIST_PROTOCOLS_BY_ID` → `ProtocolListResult`; `BALANCE_QUERY` → `BalanceResult` (ou `BalanceNoResult` quando não há saldo).","oneOf":[{"type":"object","description":"Resultado de averbação (`ENDORSEMENT`), manutenção de garantia (`MAINTAIN_GUARANTEE`) ou cancelamento (`CANCEL_RESERVE`) — protocolo retornado pela Caixa para a operação.","required":["protocolNumber","protocolStatus"],"properties":{"protocolNumber":{"type":"integer","format":"int64","description":"Número do protocolo atribuído pela Caixa."},"protocolStatus":{"type":"string","description":"Status do protocolo serializado como nome em inglês (string). De-para dos códigos Caixa: `1` → `ENDORSED` (aprovado pela Caixa), `2` → `PROCESSING` (ainda em processamento), `3` → `REJECTED` (rejeitado pela Caixa), `4` → `NOT_FOUND` (não encontrado na Caixa), `5` → `RATE_LIMITED` (chamada limitada por rate limit).","enum":["ENDORSED","PROCESSING","REJECTED","NOT_FOUND","RATE_LIMITED"]},"detail":{"type":"object","description":"Link de hypermedia para consulta do detalhe do protocolo na Caixa.","properties":{"href":{"type":"string","description":"URL para consulta do detalhe do protocolo."},"rel":{"type":"string","description":"Relação do link (ex. `self`)."}}}}},{"type":"object","description":"Resultado de consulta de valor reservado (`QUERY_RESERVED_VALUE`) — valores reservados atualizados para o identificador de reserva consultado, com períodos e valores.","required":["reserveIdentifier","workerCpf","requestDateTime","operationKind"],"properties":{"reserveIdentifier":{"type":"string","description":"Identificador lógico da reserva (formato `orig-{id}:res-{seq}`)."},"workerCpf":{"type":"string","description":"CPF do trabalhador (11 dígitos, sem pontuação)."},"requestDateTime":{"type":"string","description":"Data e hora da solicitação original (ISO-8601)."},"operationKind":{"type":"string","description":"Tipo/modalidade da operação de reserva serializado como nome em inglês (string). De-para dos códigos Caixa: `1` → `FIDUCIARY_ASSIGNMENT` (cessão fiduciária), `2` → `FIDUCIARY_ALIENATION` (alienação fiduciária).","enum":["FIDUCIARY_ASSIGNMENT","FIDUCIARY_ALIENATION"]},"periods":{"type":"array","description":"Lista de períodos com valores originais e atualizados da reserva.","items":{"type":"object","description":"Período de competência com valores original e atualizado da reserva.","required":["transferDate","periodStatus","originalAmount","updatedAmount"],"properties":{"transferDate":{"type":"string","format":"date","description":"Data de transferência (competência) do período (ISO-8601, ex. `2026-05-01`)."},"periodStatus":{"type":"string","description":"Status do período serializado como nome em inglês (string). De-para dos códigos Caixa: `1` → `GUARANTEED` (garantido/averbado), `2` → `REPAID` (quitado), `3` → `CANCELLED` (cancelado), `4` → `PAID` (pago), `5` → `PAYMENT_IN_PROGRESS` (pagamento em andamento), `6` → `PROCESSING` (em processamento), `7` → `REJECTED` (rejeitado), `8` → `CANCELLATION_IN_PROGRESS` (cancelamento em andamento), `9` → `PAYMENT_CANCELLED_FRAUD_SUSPECTED` (pagamento cancelado — suspeita de fraude).","enum":["GUARANTEED","REPAID","CANCELLED","PAID","PAYMENT_IN_PROGRESS","PROCESSING","REJECTED","CANCELLATION_IN_PROGRESS","PAYMENT_CANCELLED_FRAUD_SUSPECTED"]},"originalAmount":{"type":"number","description":"Valor original da reserva para este período."},"updatedAmount":{"type":"number","description":"Valor atualizado da reserva para este período."}}}}}},{"type":"object","description":"Resultado de consulta de protocolos por ID de reserva (`LIST_PROTOCOLS_BY_ID`) — lista de protocolos associados à reserva. Pode ser vazia quando nenhum protocolo foi encontrado.","required":["protocols"],"properties":{"protocols":{"type":"array","description":"Lista de protocolos encontrados. Pode ser vazia (`[]`).","items":{"type":"object","description":"Resultado de averbação (`ENDORSEMENT`), manutenção de garantia (`MAINTAIN_GUARANTEE`) ou cancelamento (`CANCEL_RESERVE`) — protocolo retornado pela Caixa para a operação.","required":["protocolNumber","protocolStatus"],"properties":{"protocolNumber":{"type":"integer","format":"int64","description":"Número do protocolo atribuído pela Caixa."},"protocolStatus":{"type":"string","description":"Status do protocolo serializado como nome em inglês (string). De-para dos códigos Caixa: `1` → `ENDORSED` (aprovado pela Caixa), `2` → `PROCESSING` (ainda em processamento), `3` → `REJECTED` (rejeitado pela Caixa), `4` → `NOT_FOUND` (não encontrado na Caixa), `5` → `RATE_LIMITED` (chamada limitada por rate limit).","enum":["ENDORSED","PROCESSING","REJECTED","NOT_FOUND","RATE_LIMITED"]},"detail":{"type":"object","description":"Link de hypermedia para consulta do detalhe do protocolo na Caixa.","properties":{"href":{"type":"string","description":"URL para consulta do detalhe do protocolo."},"rel":{"type":"string","description":"Relação do link (ex. `self`)."}}}}}}}},{"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."}}}]},"error":{"type":"object","description":"Erro canônico da operação FGTS. Presente no campo `error` de `OperationStatusResponse` apenas quando `status` ∈ {`FAILED`, `FAILED_NEEDS_MANUAL`, `EXPIRED`}. Representa o desfecho da operação no provedor, distinto dos erros de validação e autenticação (`400`/`429`/`401`/`403`) que usam `ProblemDetail`.","required":["code","message"],"properties":{"code":{"type":"string","description":"Código de erro canônico estável para uso programático. É o código classificado (ex.: `ENDORSEMENT_DENIED`, `PROVIDER_ERROR`, `CPF_NOT_OPERABLE`), nunca o nome do evento. Catálogo completo em https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#catalogo-operacao"},"message":{"type":"string","description":"Mensagem legível em português descrevendo o erro."},"originalErrors":{"type":"array","nullable":true,"description":"Erros crus do provedor. Presente apenas quando houve chamada ao provedor com erro — ausente em erros de validação ou de rate limiting. Lista para suportar multi-reserva (um erro por item via `requestIdentifier`).","items":{"type":"object","description":"Erro original retornado pelo provedor externo. Mapeado 1:1 do erro retornado pelo provedor mais metadados de rastreio.","required":["provider","code"],"properties":{"provider":{"type":"string","description":"Identificador do provedor que gerou o erro."},"code":{"type":"string","description":"Código de erro retornado pelo provedor (não mapeado — cru). Tabela por operação em https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#catalogo-caixa"},"description":{"type":"string","description":"Descrição textual do erro retornada pelo provedor."},"httpStatus":{"type":"integer","format":"int32","description":"HTTP status retornado pelo provedor na chamada original."},"requestIdentifier":{"type":"string","description":"Identificador de rastreio da solicitação no provedor. Em multi-reserva, permite atribuir o erro ao item específico."},"occurredAt":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no provedor (ISO-8601 UTC)."}}}},"originalRequestId":{"type":"string","nullable":true,"description":"Presente quando `code` ∈ {`ENDORSEMENT_ALREADY_SUBMITTED`, `GUARANTEE_OPERATION_DUPLICATE`, `GUARANTEE_APPROVAL_ALREADY_PENDING`}: o `requestId` da operação que de fato está em andamento (ou concluída). Consulte-o para acompanhar o desfecho real. Já quando `code` ∈ {`ENDORSEMENT_RETRY_LIMIT_EXCEEDED`, `ENDORSEMENT_NOT_RETRYABLE`, `ENDORSEMENT_RETRY_UNSUPPORTED_LEGACY_RECORD`} esta própria operação já é o desfecho terminal; `originalRequestId` é apenas correlação com o `requestId` da averbação original da reserva."}}},"retry":{"allOf":[{"type":"object","description":"Progresso da janela de retentativa automática da averbação. A Caixa devolveu um código transiente e o dispatcher reenvia a mesma reserva a cada 15 minutos por até 72 horas.","properties":{"providerAttempt":{"type":"integer","format":"int32","nullable":true,"description":"Tentativas automáticas **nossas** já feitas nesta janela (até ~288 em 72h). **Não** é o seu orçamento de retentativas manuais, que é de 3 por reserva."},"nextAttemptAt":{"type":"string","format":"date-time","nullable":true},"windowExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Fim da janela. Depois disso a operação encerra com `error.code = TRANSIENT_PROVIDER_RETRY_EXHAUSTED` e a retentativa manual passa a ser aceita."},"eligible":{"type":"boolean","nullable":true,"description":"Sempre `false` durante a janela: `POST /endorsements/{reserveIdentifier}/retries` responderia `409 ENDORSEMENT_NOT_RETRYABLE`."},"lastProviderError":{"allOf":[{"type":"object","description":"Erro original retornado pelo provedor externo. Mapeado 1:1 do erro retornado pelo provedor mais metadados de rastreio.","required":["provider","code"],"properties":{"provider":{"type":"string","description":"Identificador do provedor que gerou o erro."},"code":{"type":"string","description":"Código de erro retornado pelo provedor (não mapeado — cru). Tabela por operação em https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros#catalogo-caixa"},"description":{"type":"string","description":"Descrição textual do erro retornada pelo provedor."},"httpStatus":{"type":"integer","format":"int32","description":"HTTP status retornado pelo provedor na chamada original."},"requestIdentifier":{"type":"string","description":"Identificador de rastreio da solicitação no provedor. Em multi-reserva, permite atribuir o erro ao item específico."},"occurredAt":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no provedor (ISO-8601 UTC)."}}}],"nullable":true,"description":"O que a Caixa respondeu na tentativa que colocou a operação na janela. Fica aqui e **não** em `error` porque a operação não falhou — ela ainda será tentada, e preencher `error` faria um cliente em polling ler \"em andamento\" como \"falhou\".\n\nÉ este campo que diz se há algo a fazer. Código **7** (`HTTP 403`) é autorização pendente: peça ao trabalhador que autorize a operação no app do FGTS, e a próxima tentativa converte — medido em produção, a mediana é de 4 a 5 tentativas em cerca de 75 minutos. Já **3**, **14** e **524** são instabilidade da Caixa, sem ação possível do seu lado além de aguardar."}}}],"nullable":true,"description":"Presente **apenas** enquanto `status = RETRYING` por janela de retentativa automática da averbação. Some assim que a operação se resolve."},"estimatedWaitSeconds":{"type":"integer","format":"int32","nullable":true,"description":"Estimativa best-effort de segundos até a conclusão. Não é garantia de prazo. `null` quando não disponível ou em estados terminais."},"reserveIdentifier":{"type":"string","nullable":true,"description":"Identificador da reserva associada à operação, quando aplicável (`ENDORSEMENT`, `CANCEL_RESERVE`, `MAINTAIN_GUARANTEE`). Use este valor para retentar a averbação (`POST /endorsements/{reserveIdentifier}/retries`), cancelar ou consultar a garantia. `null` para operações sem reserva associada."}}}}}},"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."}}}}}},"403":{"description":"Acesso negado — a operação não pertence ao originator autenticado (acesso cruzado entre originators).","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":"Operação não encontrada — `requestId` inexistente ou ainda não registrado.","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":"Consulta temporariamente indisponível. `DISPATCHER_UNAVAILABLE` (`Retry-After: 30`) quando o processamento de operações está indisponível; `GUARANTEE_LEDGER_UNAVAILABLE` quando a operação depende do serviço de garantias (averbação, cancelamento de reserva, manutenção de garantia).","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."}}}}}}}}}}}
```

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