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

# Cancelar Contrato

Cancela um contrato que ainda não entrou em assinatura, averbação ou formalização.

## Request

`POST /api/v1/originator/contracts/cancel`

Autenticação: `Authorization: Bearer {originatorToken}`. Sem corpo: o identificador vai na query.

### Parâmetros

| Parâmetro        | Local | Tipo     | Obrigatório | Descrição                        |
| ---------------- | ----- | -------- | ----------- | -------------------------------- |
| `requestNumber`  | query | `string` | Condicional | Número da requisição do contrato |
| `contractNumber` | query | `string` | Condicional | Número do contrato (CCB)         |

Informe **exatamente um** dos dois (máx. 100 caracteres cada); ambos ou nenhum dá `400`.

## Regras de cancelamento

* Só é permitido enquanto o contrato **não entrou em assinatura/averbação/formalização** — a plataforma confere o status do contrato, da averbação e da formalização.
* Em estágio avançado, a API responde `409 Conflict`.

## Response

`200 OK` com o contrato no mesmo formato de [Buscar Contrato](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/buscar-contrato-por-request-number.md#response), com `status: CANCELLED`. `rejectionReason` vem `null`; `cancelReason` traz o motivo em texto livre quando registrado (ex.: `Cancelado pelo funcionário`).

## Exemplo

```http
POST /api/v1/originator/contracts/cancel?requestNumber=GTAB12CD34EF HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
```

Resposta `200`:

```json
{
  "requestNumber": "GTAB12CD34EF",
  "contractNumber": "00345678",
  "employeePublicId": "Kj8mP2xQ9nR4sT6v",
  "status": "CANCELLED",
  "endorsementStatus": "PENDING",
  "contractAmount": 5000,
  "installments": 12,
  "contractDate": "2025-01-15",
  "firstInstallmentDueDate": "2025-04-28",
  "lastInstallmentDueDate": "2026-03-28",
  "totalInterestAmount": 1250,
  "debitAmount": 7125.36,
  "monthlyInterestRate": 1.99,
  "monthlyEffectiveCost": 2.15,
  "annualEffectiveCost": 28.97,
  "disbursementAmount": 4800,
  "insuranceAmount": 87.3,
  "iofAmount": 45.2,
  "tacAmount": 0,
  "attendantName": "Maria Atendente",
  "attendantCpf": "98765432100",
  "bankInfo": {
    "type": "PIX",
    "pix": {
      "keyType": "CPF",
      "key": "12345678901"
    }
  },
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 101",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01234567"
  },
  "documentStatus": "CANCELLED",
  "nsu": "1234567890123456789",
  "rejectionReason": null,
  "cancelReason": "Cancelado pelo originador",
  "createdDate": "2025-01-15T10:00:00Z"
}
```

## Erros

| Código | `errorCode`                  | Situação                                                                                                                                                                                                                                                                                                                                                                              |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | —                            | Nenhum ou ambos os identificadores, ou identificador acima de 100 caracteres. Esta resposta **não traz mensagem** no corpo                                                                                                                                                                                                                                                            |
| 404    | —                            | Contrato não encontrado ou de outro originador                                                                                                                                                                                                                                                                                                                                        |
| 409    | —                            | title `Contract cancellation not allowed`: contrato já em assinatura, averbado, formalizado ou cancelado. `properties` traz `publicId`, `requestNumber`, `contractNumber`, `contractStatus`, `endorsementStatus` e `formalizationStatus`. Contrato averbado usa a [desaverbação](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/contratos/desaverbar-contrato.md) |
| 423    | `DATAPREV_SUSPENSION_WINDOW` | Janela de suspensão da Dataprev                                                                                                                                                                                                                                                                                                                                                       |
| 429    | —                            | Mais de 75 requisições por segundo                                                                                                                                                                                                                                                                                                                                                    |

Erros comuns a todos os endpoints — `401`, `403` de token, `409` de `Idempotency-Key` em processamento, `500` e `503` — e o formato `ProblemDetail` estão em [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

## Cancelar Contrato

> Cancela um contrato do originator usando \*\*um único identificador\*\*:\
> \- \`publicId\` (ou o legado \`requestNumber\`) \*\*ou\*\*\
> \- \`contractNumber\`\
> \
> Regras de negócio:\
> \- O contrato é carregado com lock pessimista antes da atualização.\
> \- O cancelamento só é permitido quando o contrato ainda não entrou em assinatura/averbação/formalização.\
> \- Após o lock, o backend valida o status do contrato e também os status de Endorsement e Formalization.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Contracts","description":"Contratos de empréstimo"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/contracts/cancel":{"post":{"summary":"Cancelar Contrato","description":"Cancela um contrato do originator usando **um único identificador**:\n- `publicId` (ou o legado `requestNumber`) **ou**\n- `contractNumber`\n\nRegras de negócio:\n- O contrato é carregado com lock pessimista antes da atualização.\n- O cancelamento só é permitido quando o contrato ainda não entrou em assinatura/averbação/formalização.\n- Após o lock, o backend valida o status do contrato e também os status de Endorsement e Formalization.\n","tags":["Contracts"],"parameters":[{"name":"publicId","in":"query","required":false,"description":"Identificador público do contrato (enviar apenas quando contractNumber não for informado)","schema":{"type":"string","maxLength":36}},{"name":"requestNumber","in":"query","required":false,"description":"Identificador legado do contrato. Mantido para os integradores que ainda não migraram.\nIgnorado quando `publicId` é informado. Enviar apenas quando `contractNumber` não for informado.\n","schema":{"type":"string"}},{"name":"contractNumber","in":"query","required":false,"description":"Número do contrato (enviar apenas quando publicId não for informado)","schema":{"type":"string"}}],"responses":{"200":{"description":"Contrato cancelado com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"publicId":{"type":"string","maxLength":36,"description":"Identificador público do contrato. Pode vir omitido (ausente no JSON) em contratos antigos."},"requestNumber":{"type":"string","maxLength":36,"description":"Número da requisição do contrato. Contratos criados a partir da adoção do `publicId` nascem com o mesmo valor dele (UUID de 36 caracteres); anteriores mantêm o formato legado GT + 10 alfanuméricos maiúsculos. Ex. GTAB12CD34EF"},"contractNumber":{"type":"string","description":"Número do contrato (8 dígitos com zero à esquerda).\nPor padrão (estratégia GIRO), o número é gerado automaticamente pela plataforma.\nNa estratégia ORIGINATOR_MANAGED, o originador pode informar o número no momento da criação do contrato.\n"},"dataprevContractNumber":{"type":"string","nullable":true,"maxLength":30,"description":"Identificador do contrato perante o Dataprev — corresponde ao campo `numeroContrato`\ntrocado com o Dataprev em averbação, alteração, suspensão, reativação e exclusão.\nUse este valor para correlacionar o contrato na GTPayroll com os registros do Dataprev.\n\nTrate como **string opaca**: o formato não faz parte do contrato e pode mudar sem\naviso. Não derive nem reconstrua o valor a partir de outros campos.\n\nPode vir `null` em contratos legados criados antes da introdução do campo.\n"},"employeePublicId":{"type":"string","description":"Identificador público do trabalhador (16 caracteres Base64 URL-safe)."},"proposal":{"type":"object","properties":{"publicId":{"type":"string","description":"Identificador público (16 caracteres Base64 URL-safe). Ex. Kj8mP2xQ9nR4sT6v"},"employeePublicId":{"type":"string","description":"Identificador público opaco do employee (16 caracteres Base64 URL-safe). Pode vir ausente em registros antigos.","nullable":true},"simulationPublicId":{"type":"string","format":"uuid","nullable":true,"description":"Identificador público opaco da simulação de referência, quando houver."},"loanAmount":{"type":"number","format":"decimal","description":"Valor do empréstimo em reais (decimal com 2 casas decimais)."},"financedAmount":{"type":"number","format":"decimal","description":"Valor financiado em reais (decimal com 2 casas decimais)."},"totalInterestAmount":{"type":"number","format":"decimal","description":"Juros totais em reais (decimal com 2 casas decimais)."},"debitAmount":{"type":"number","format":"decimal","minimum":0,"description":"Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places)."},"monthlyInterestRate":{"type":"number","format":"decimal","description":"Taxa mensal em percentual (decimal com 4 casas decimais)."},"annualInterestRate":{"type":"number","format":"decimal","description":"Taxa de juros anual em percentual (snapshot da proposta)."},"monthlyEffectiveCost":{"type":"number","format":"decimal","description":"CET mensal em percentual (decimal com 4 casas decimais)."},"annualEffectiveCost":{"type":"number","format":"decimal","description":"CET anual em percentual (decimal com 4 casas decimais)."},"disbursementAmount":{"type":"number","format":"decimal","description":"Valor a desembolsar em reais (decimal com 2 casas decimais)."},"insuranceAmount":{"type":"number","format":"decimal","description":"Seguro em reais (decimal com 2 casas decimais)."},"iofAmount":{"type":"number","format":"decimal","description":"IOF em reais (decimal com 2 casas decimais)."},"tacAmount":{"type":"number","format":"decimal","description":"TAC em reais. Sempre `0`; valor diferente responde `400 TAC_NOT_ALLOWED`."},"outstandingBalance":{"type":"number","format":"decimal","description":"Saldo devedor em reais (decimal com 2 casas decimais)."},"installmentCount":{"type":"integer"},"dueDate":{"type":"string","format":"date"},"status":{"type":"string","enum":["PENDING","ACCEPTED","REJECTED","EXPIRED","CONVERTED_TO_CONTRACT"],"description":"Status da proposta.\n| Valor | Significado |\n|-------|-------------|\n| PENDING | Aguardando aceite do trabalhador |\n| ACCEPTED | Aceita pelo trabalhador |\n| REJECTED | Rejeitada pelo trabalhador |\n| EXPIRED | Expirada (prazo de aceite) |\n| CONVERTED_TO_CONTRACT | Convertida em contrato |\n"},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","format":"date-time"},"installments":{"type":"array","items":{"type":"object","properties":{"installmentNumber":{"type":"integer","description":"Número da parcela (1-based)."},"dueDate":{"type":"string","format":"date","description":"Data de vencimento da parcela."},"installmentAmount":{"type":"number","format":"decimal","description":"Valor da parcela (desconto em folha) em reais."},"amortizationAmount":{"type":"number","format":"decimal","description":"Amortização (principal) da parcela em reais."},"interestAmount":{"type":"number","format":"decimal","description":"Juros da parcela em reais."},"iofAmount":{"type":"number","format":"decimal","description":"IOF da parcela em reais."},"feesAmount":{"type":"number","format":"decimal","description":"Taxas da parcela em reais."},"outstandingBalance":{"type":"number","format":"decimal","description":"Saldo devedor após a parcela em reais."},"daysToCompensate":{"type":"integer","description":"Dias para compensação."},"documentNumber":{"type":"string","maxLength":10,"description":"Número identificador do vencimento informado na criação da proposta. Vazio quando o originador não enviou; nesse caso a CCB vai ao banco emissor com o número da CCB seguido da parcela em dois dígitos (`0000000101`)."},"ourNumber":{"type":"string","maxLength":32,"description":"Nosso número do documento no banco emissor."},"ourNumberBankCode":{"type":"string","maxLength":3,"description":"Código do banco do nosso número do documento."},"participantControl":{"type":"string","maxLength":25,"description":"Controle do participante informado na criação da proposta. Vazio quando o originador não enviou; nesse caso a CCB vai ao banco emissor com o número da CCB, hífen e a parcela em dois dígitos (`00000001-01`)."}}}},"createdDate":{"type":"string","format":"date-time"}},"description":"Proposta completa que originou o contrato, incluindo a lista de parcelas (installments)."},"status":{"type":"string","enum":["CREATED","SIGNED","ENDORSED","FORMALIZED","COMPLETED","CANCELLED"],"description":"Ciclo de vida do contrato.\n| Valor | Significado |\n|-------|-------------|\n| CREATED | Contrato criado, aguardando assinatura |\n| SIGNED | Assinado pelo trabalhador |\n| ENDORSED | Averbação consignada confirmada |\n| FORMALIZED | Formalizado no sistema de pagamento |\n| COMPLETED | Operação concluída (desembolsado) |\n| CANCELLED | Cancelado |\n"},"endorsementStatus":{"type":"string","enum":["PENDING","PROCESSING","ENDORSED","FAILED","RETRYING","EXCLUDING","EXCLUDED"],"description":"Situação da averbação no convênio.\n| Valor | Significado |\n|-------|-------------|\n| PENDING | Aguardando averbação |\n| PROCESSING | Em processamento no convênio |\n| ENDORSED | Averbação confirmada |\n| FAILED | Falha na averbação |\n| RETRYING | Nova tentativa em andamento |\n"},"endorsementProtocol":{"type":"string","description":"Protocolo retornado pelo provedor de averbação, quando disponível."},"contractAmount":{"type":"number","format":"decimal","description":"Valor principal do contrato em reais (decimal com 2 casas decimais)."},"installments":{"type":"integer","description":"Quantidade de parcelas definida no contrato."},"contractDate":{"type":"string","format":"date","description":"Data de contratação (yyyy-MM-dd)."},"firstInstallmentDueDate":{"type":"string","format":"date","description":"Data de vencimento da primeira parcela."},"lastInstallmentDueDate":{"type":"string","format":"date","description":"Data de vencimento da última parcela."},"signedAt":{"type":"string","format":"date-time","description":"Data e hora em que o contrato foi assinado (UTC)."},"formalizedAt":{"type":"string","format":"date-time","description":"Data e hora em que a formalização foi concluída (UTC)."},"paidAt":{"type":"string","format":"date-time","description":"Data e hora de liquidação/desembolso do contrato (UTC)."},"paymentReceiptUrl":{"type":"string","format":"uri","nullable":true,"maxLength":512,"description":"URL do comprovante de pagamento emitido pela instituição de pagamento no desembolso. Presente após o pagamento, inclusive desembolso após cancelamento (contrato CANCELLED); permanente; não exige autenticação — trate como dado sensível."},"endorsedAt":{"type":"string","format":"date-time","description":"Data e hora de confirmação da averbação (UTC)."},"totalInterestAmount":{"type":"number","format":"decimal","description":"Valor total de juros da operação em reais (decimal com 2 casas decimais)."},"debitAmount":{"type":"number","format":"decimal","minimum":0,"description":"Total repayment amount (installmentCount × installmentAmount) in reais (decimal with 2 decimal places)."},"monthlyInterestRate":{"type":"number","format":"decimal","description":"Taxa de juros mensal em percentual (decimal com 4 casas decimais)."},"monthlyEffectiveCost":{"type":"number","format":"decimal","description":"Custo efetivo mensal (CET mensal) em percentual (decimal com 4 casas decimais)."},"annualEffectiveCost":{"type":"number","format":"decimal","description":"Custo efetivo anual (CET anual) em percentual (decimal com 4 casas decimais)."},"disbursementAmount":{"type":"number","format":"decimal","description":"Valor líquido desembolsado ao trabalhador em reais (decimal com 2 casas decimais)."},"insuranceAmount":{"type":"number","format":"decimal","description":"Valor do seguro prestamista em reais (decimal com 2 casas decimais)."},"iofAmount":{"type":"number","format":"decimal","description":"Valor do IOF incidente na operação em reais (decimal com 2 casas decimais)."},"tacAmount":{"type":"number","format":"decimal","description":"Valor da TAC (Taxa de Abertura de Crédito) em reais (decimal com 2 casas decimais)."},"attendantName":{"type":"string","maxLength":150,"description":"Nome do atendente ou vendedor responsável pela venda."},"attendantCpf":{"type":"string","maxLength":14,"description":"CPF do atendente ou vendedor responsável."},"bankInfo":{"description":"Informações de destino financeiro para pagamento/desembolso.","type":"object","properties":{"type":{"type":"string","description":"Modalidade de destino financeiro utilizada (PIX ou BANK_ACCOUNT)."},"pix":{"description":"Dados de chave Pix utilizados, quando aplicável.","type":"object","properties":{"keyType":{"type":"string","description":"Tipo da chave Pix registrada no contrato."},"key":{"type":"string","description":"Valor da chave Pix registrada."}}},"bankAccount":{"description":"Dados bancários utilizados, quando aplicável.","type":"object","properties":{"bankCode":{"type":"string","description":"Código do banco registrado no contrato."},"branchNumber":{"type":"string","description":"Agência bancária registrada."},"branchDigit":{"type":"string","description":"Dígito da agência registrado."},"accountNumber":{"type":"string","description":"Número da conta registrada."},"accountDigit":{"type":"string","description":"Dígito da conta registrado."},"accountType":{"type":"string","description":"Tipo da conta registrada para desembolso."}}}}},"address":{"description":"Endereço associado ao contrato.","type":"object","properties":{"street":{"type":"string","description":"Logradouro registrado no contrato."},"number":{"type":"string","description":"Número do imóvel registrado."},"complement":{"type":"string","description":"Complemento do endereço registrado."},"neighborhood":{"type":"string","description":"Bairro registrado."},"city":{"type":"string","description":"Cidade registrada."},"state":{"type":"string","description":"UF registrada."},"zipCode":{"type":"string","description":"CEP registrado."}}},"createdDate":{"type":"string","format":"date-time","description":"Data e hora de criação do contrato no sistema (UTC)."},"nsu":{"type":"string","maxLength":19,"description":"NSU (Número Sequencial Único) do documento do contrato.\nUsado para rastreamento em ambas as estratégias (GIRO e ORIGINATOR_MANAGED); na ORIGINATOR_MANAGED também para referência no upload do documento assinado.\n"},"documentStatus":{"type":"string","enum":["PENDING","GENERATED","PENDING_SIGNATURE","SIGNATURE_PENDING_RETRY","SIGNED","REJECTED","EXPIRED","CANCELLED","FAILED","PROCESSED"],"description":"Status do documento do contrato (DocumentStatus).\n| Valor | Significado |\n|-------|-------------|\n| PENDING | Aguardando geração do PDF |\n| GENERATED | PDF gerado, aguardando assinatura/upload |\n| PENDING_SIGNATURE | Aguardando assinatura |\n| SIGNATURE_PENDING_RETRY | Reenvio de link de assinatura em andamento |\n| SIGNED | Documento assinado recebido |\n| REJECTED | Documento rejeitado |\n| EXPIRED | Documento/link expirado |\n| CANCELLED | Documento cancelado |\n| FAILED | Falha na geração do documento |\n| PROCESSED | Documento processado |\n"},"rejectionReason":{"type":"string","nullable":true,"description":"Motivo da pendência de **desembolso**, em texto livre destinado a leitura humana.\n\nPreenchido por dois eventos do GTBanker, e apenas por eles:\n| Evento GTBanker | Webhook correspondente | Conteúdo |\n|-----------------|------------------------|----------|\n| `REVISAO_DESEMBOLSO` | `PAYMENT_REVISION` | `Revisão de conta de desembolso necessária - Ticket: <ticket>` |\n| `FALHA_DESEMBOLSO` | `PAYMENT_FAILURE` | `Falha no pagamento - Código: <codigo> - <mensagem>` |\n\nNesses dois casos o contrato permanece em `FORMALIZED` — o status não muda.\n\nO contrato também registra internamente falhas de formalização e de geração de documento,\nmas essas **não são expostas** neste campo: são diagnóstico de plataforma e chegam como\n`null` aqui. Um contrato `CANCELLED` por falha de geração de documento, portanto, tem\n`rejectionReason` nulo — para cancelamento, veja `cancelReason`.\n\nO campo é **limpo** quando o desembolso é concluído com sucesso (`PAYMENT_SUCCESS`), então\num contrato `COMPLETED` não carrega pendência antiga.\n\nTrate como **texto opaco para exibição**: o formato não faz parte do contrato e pode mudar\nsem aviso. Para lógica de negócio, use o payload do webhook, que traz `ticket`, `codigo` e\n`mensagem` em campos separados.\n\n`null` enquanto não houver pendência de desembolso.\n"},"cancelReason":{"type":"string","nullable":true,"description":"Motivo do cancelamento do contrato, em texto livre destinado a leitura humana.\n\nPreenchido quando o contrato vai a `CANCELLED` por cancelamento do trabalhador\n(`Cancelado pelo funcionário`) ou por exclusão da averbação, caso em que traz o motivo da\ndesaverbação. Complementa `rejectionReason`, que cobre apenas pendência de desembolso.\n\nTrate como **texto opaco para exibição**. `null` enquanto o contrato não for cancelado.\n"},"suppressNotification":{"type":"boolean","description":"Indica se a notificação WhatsApp ao assinador foi suprimida (URL entregue via webhook ao originador)."},"signatureExpirationDate":{"type":"string","format":"date","nullable":true,"description":"Data limite de assinatura informada na criação do contrato. `null` quando o originador não\ninformou — nesse caso vale o padrão do provedor de assinatura. Devolve o que foi pedido, não\no prazo efetivo, que só é resolvido quando o link é gerado.\n"},"currentBond":{"description":"Vínculo em que o contrato está agora: o destino da migração automática mais recente ou, sem\nmigração, o vínculo em que o contrato foi averbado. `null` quando a proposta não tem vínculo.\n","type":"object","properties":{"registrationNumber":{"type":"string","maxLength":100,"description":"Matrícula do trabalhador no empregador."},"employerRegistrationTypeCode":{"type":"integer","description":"Tipo de inscrição do empregador (1 = CNPJ, 2 = CPF)."},"employerRegistrationNumber":{"type":"string","maxLength":20,"description":"Inscrição do empregador como a Dataprev a identifica: raiz do CNPJ com 8 dígitos ou CPF com\n11. Para o documento completo use `employerTaxId`.\n"},"employerTaxId":{"type":"string","description":"Documento completo do empregador, sem máscara: CPF com 11 dígitos ou CNPJ com 14. Quando só\nse tem a raiz do CNPJ, o valor é o da **matriz** (raiz + filial `0001` + dígitos\nverificadores), que pode não ser o estabelecimento onde o trabalhador está lotado. Ausente\nquando não é possível afirmar um documento válido.\n"},"employerName":{"type":"string","maxLength":200}}}}}}}},"400":{"description":"- Identificadores inválidos: informe apenas um identificador (publicId, ou o legado requestNumber, ou contractNumber).\n- Regra de negócio: contrato não encontrado ou não pertence ao originator (resposta com title \"Bad Request\", detail com a mensagem do erro).\n","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"401":{"description":"Não autenticado","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Permissão insuficiente","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"404":{"description":"Contrato não encontrado","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"409":{"description":"Contrato não pode ser cancelado porque já está em assinatura/averbação/formalização","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro 409 específico do cancelamento de contrato (`type` `#conflict`). Os status do contrato, da\naverbação e da formalização vêm em `properties` para diagnóstico.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","properties":{"message":{"type":"string"},"publicId":{"type":"string","maxLength":36,"description":"Identificador público do contrato. Pode vir omitido em contratos antigos."},"requestNumber":{"type":"string","maxLength":36},"contractNumber":{"type":"string"},"contractStatus":{"type":"string"},"endorsementStatus":{"type":"string"},"formalizationStatus":{"type":"string"}}}}}}}},"423":{"description":"Janela de suspensão da Dataprev aberta (virada de competência). A operação **não** foi\nregistrada — reenvie depois de `windowEnd`.\n\nOnde olhar para reagendar: o header `Retry-After` traz os **segundos** que faltam (é sempre\ndelta-seconds, nunca HTTP-date) e o corpo traz `windowEnd` como `date-time`. Use um dos dois —\n**não** faça backoff exponencial, a volta tem hora marcada.\n","headers":{"Retry-After":{"description":"Segundos até o fim previsto da janela.","schema":{"type":"integer","format":"int32"}}},"content":{"application/problem+json":{"schema":{"type":"object","description":"Recusa por janela de suspensão da Dataprev (virada de competência). A Dataprev suspende as\noperações mensalmente, por volta do dia 21 ao dia 23, e nesse período o GTPayroll recusa de\nimediato em vez de aceitar um pedido que ficaria dias sem resposta.\n\nUse o header `Retry-After` para reagendar: **não** faça backoff exponencial, a volta tem hora\nmarcada. A recusa fica gravada na `Idempotency-Key` — reenvie com chave nova. Simulação,\npropostas e webhooks continuam disponíveis durante a janela; o webhook `DATAPREV_WINDOW_CLOSED`\navisa quando as demais rotas voltam.\n","required":["type","title","status","properties"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","required":["errorCode"],"properties":{"message":{"type":"string"},"errorCode":{"type":"string"},"windowEnd":{"type":"string","description":"Fim previsto da janela, em data/hora **sem fuso** (`yyyy-MM-ddTHH:mm:ss`). Ausente quando a Dataprev não informou a data."}}}}}}}},"429":{"description":"Mais de 75 requisições por segundo. Aguarde o header `Retry-After` e reenvie com **nova** `Idempotency-Key` — com a mesma chave, o `429` gravado é repetido.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

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