Erros

Formato das respostas de erro

As APIs de negócio (Workflow e Cadastro) devolvem erros no formato Problem Details (RFC 9457), com o tipo de conteúdo application/problem+json.

Campo	Descrição
`title`	Resumo curto do problema.
`status`	Código de status HTTP.
`detail`	Explicação específica da ocorrência. Presente apenas quando houver.
`requestId`	Identificador da requisição, igual ao header `X-Request-Id`.

O contrato também prevê o campo opcional type.

{
"title": "Unprocessable Entity",
"status": 422,
"detail": "Título vazio.",
"requestId": "00000000-0000-0000-0000-000000000000"
}

Os textos de title e detail acima são ilustrativos. Não baseie a lógica da sua integração neles: use o código de status.

Identificador da requisição

Toda resposta, de sucesso ou de erro, traz o header X-Request-Id. Nos erros, o mesmo valor aparece no campo requestId do corpo.

Registre esse identificador nos logs da sua integração e cite-o ao falar com o suporte: é ele que permite localizar a chamada. Veja Suporte.

Catálogo de erros

Status	Quando ocorre	O que fazer
`400`	Requisição malformada (por exemplo, CNPJ fora do formato).	Corrija a requisição antes de repetir.
`401`	Token ausente, expirado ou inválido; ou chave de assinatura (`Ocp-Apim-Subscription-Key`) ausente ou inválida.	Obtenha um novo token e repita a chamada. Veja Autenticação. Se o token estiver correto, confira a chave de assinatura.
`403`	Token válido, mas sem a função exigida pela operação.	Confira as funções do seu cadastro.
`404`	Recurso não encontrado (tarefa ou cliente).	Confira o identificador informado.
`422`	Campos inválidos (por exemplo, título vazio ou área de negócio desconhecida).	Corrija os campos e repita.
`429`	Limite de chamadas excedido.	Aguarde o tempo do header `Retry-After`. Veja Limites de chamadas.
`502`	Falha no sistema que atende a requisição (processamento da tarefa ou origem dos dados).	Tente novamente mais tarde; se persistir, acione o Suporte com o `requestId`.

Os códigos possíveis de cada operação estão na referência de cada API.

Chave de assinatura ausente ou inválida

Nas APIs de negócio, a ausência ou a invalidade do header Ocp-Apim-Subscription-Key resulta em 401. Para esse caso, o contrato garante apenas o status: não dependa de um formato específico para o corpo da resposta. Veja Solicitação de acesso.

Headers `WWW-Authenticate`

As respostas 401 e 403 incluem o header WWW-Authenticate.

Erros da rota de token

A rota POST /auth/v1/token é uma exceção: seus erros seguem o formato OAuth 2.0 (RFC 6749), que as bibliotecas de autenticação esperam.

Campo	Descrição
`error`	Código do erro OAuth 2.0 (por exemplo, `invalid_client` ou `invalid_grant`).
`error_description`	Descrição do erro. Opcional.

{
"error": "invalid_client",
"error_description": "Credenciais inválidas."
}

Status	Quando ocorre
`400`	Requisição inválida, ou parceiro sem acesso à API pedida (por exemplo, `error` igual a `invalid_grant`).
`401`	Credenciais inválidas (`client_id` ou `client_secret`), com `error` igual a `invalid_client`. Confira se o segredo foi copiado exatamente como entregue.
`429`	Limite de chamadas excedido. Neste caso, o corpo segue o formato Problem Details e há o header `Retry-After`.