Referência

Erros

Toda falha responde application/problem+json (RFC 9457). O campo type é uma URI estável — https://app.apogeu.ia.br/developers/erros#<tipo> — que aponta para a âncora correspondente nesta página. Programe contra o type e, na validação, contra o campo de errors[]; não contra o texto de title, detail ou mensagem, que vem em português e pode mudar. Semântica de retentativa e exemplos de fluxo estão na seção Erros do guia.

Envelope

Campo	Sempre?	Significado
`type`	sim	URI do tipo de erro (âncora desta página).
`title`	sim	Título curto, fixo por tipo.
`status`	sim	Código HTTP, repetido no corpo.
`detail`	não	Explicação desta ocorrência (genérica em autenticação).
`errors[]`	não	Em validação: lista de { campo, mensagem }.

exemplo

{
  "type": "https://app.apogeu.ia.br/developers/erros#parametro-invalido",
  "title": "Parâmetro inválido",
  "status": 400,
  "detail": "Um ou mais parâmetros são inválidos.",
  "errors": [
    {
      "campo": "limit",
      "mensagem": "Muito grande: esperado que number fosse <=100"
    }
  ]
}

Catálogo

HTTP	Tipo	Título
401	credencial-invalida	Credencial inválida ou revogada
403	escopo-insuficiente	Escopo insuficiente
404	nao-encontrado	Recurso não encontrado
400	parametro-invalido	Parâmetro inválido
400	cursor-invalido	Cursor inválido ou expirado
429	limite-excedido	Limite de requisições excedido
500	erro-interno	Erro interno
422	idempotency-key-reuse	Idempotency-Key reutilizada com outro corpo
409	idempotency-in-flight	Requisição idêntica em andamento
409	estado-invalido	O estado atual não permite a operação

401 · credencial-invalida

Credencial inválida ou revogada

type: https://app.apogeu.ia.br/developers/erros#credencial-invalida
Quando ocorre: Cabeçalho Authorization ausente ou malformado; chave inexistente, revogada ou expirada; escritório sem assinatura ativa. A mensagem é genérica de propósito.
Retentar?: Não. Corrija a chave (ou emita outra) antes de chamar de novo; se o escritório estiver sem assinatura ativa, fale com o administrador da plataforma.

401

{
  "type": "https://app.apogeu.ia.br/developers/erros#credencial-invalida",
  "title": "Credencial inválida ou revogada",
  "status": 401
}

403 · escopo-insuficiente

Escopo insuficiente

type: https://app.apogeu.ia.br/developers/erros#escopo-insuficiente
Quando ocorre: A chave autentica, mas não carrega o escopo que a operação exige; detail nomeia o escopo.
Retentar?: Não. Reemita a chave com o escopo indicado.

403

{
  "type": "https://app.apogeu.ia.br/developers/erros#escopo-insuficiente",
  "title": "Escopo insuficiente",
  "status": 403
}

404 · nao-encontrado

Recurso não encontrado

type: https://app.apogeu.ia.br/developers/erros#nao-encontrado
Quando ocorre: O recurso não existe, não pertence ao seu escritório ou está em segredo de justiça — a resposta é a mesma nos três casos.
Retentar?: Não. Confira o id; a API não confirma nem nega existência fora do seu escritório.

404

{
  "type": "https://app.apogeu.ia.br/developers/erros#nao-encontrado",
  "title": "Recurso não encontrado",
  "status": 404
}

400 · parametro-invalido

Parâmetro inválido

type: https://app.apogeu.ia.br/developers/erros#parametro-invalido
Quando ocorre: Query, path ou corpo fora do contrato; errors[] lista o campo e a mensagem, em português.
Retentar?: Só depois de corrigir os campos apontados.

400

{
  "type": "https://app.apogeu.ia.br/developers/erros#parametro-invalido",
  "title": "Parâmetro inválido",
  "status": 400
}

400 · cursor-invalido

Cursor inválido ou expirado

type: https://app.apogeu.ia.br/developers/erros#cursor-invalido
Quando ocorre: Cursor de paginação corrompido, de outra listagem ou expirado.
Retentar?: Recomece a listagem sem cursor, com os mesmos filtros.

400

{
  "type": "https://app.apogeu.ia.br/developers/erros#cursor-invalido",
  "title": "Cursor inválido ou expirado",
  "status": 400
}

429 · limite-excedido

Limite de requisições excedido

type: https://app.apogeu.ia.br/developers/erros#limite-excedido
Quando ocorre: Estouro de um dos tetos do minuto corrente (por chave ou por escritório) ou do teto próprio de uma operação, que o detail nomeia: mensagens avulsas de WhatsApp e audiências marcadas por dia, importações de modelo por IA no mês.
Retentar?: No teto por minuto, sim: após os segundos de Retry-After, não antes. No teto de uma operação a resposta vem sem Retry-After: só no dia ou no mês seguinte, como o detail diz.

429

{
  "type": "https://app.apogeu.ia.br/developers/erros#limite-excedido",
  "title": "Limite de requisições excedido",
  "status": 429
}

500 · erro-interno

Erro interno

type: https://app.apogeu.ia.br/developers/erros#erro-interno
Quando ocorre: Falha inesperada do lado da API; o corpo nunca traz detalhes internos.
Retentar?: Sim, com recuo exponencial (ex.: 1s, 2s, 4s). Escritas sem Idempotency-Key podem duplicar — verifique antes de repetir; com a chave, repita a mesma requisição com segurança.

500

{
  "type": "https://app.apogeu.ia.br/developers/erros#erro-interno",
  "title": "Erro interno",
  "status": 500
}

422 · idempotency-key-reuse

Idempotency-Key reutilizada com outro corpo

type: https://app.apogeu.ia.br/developers/erros#idempotency-key-reuse
Quando ocorre: A mesma Idempotency-Key já foi usada nesta operação, por esta credencial, com um corpo diferente, nas últimas 24 horas.
Retentar?: Não com esta chave. Uma requisição diferente é uma chave nova; a repetição exata da anterior continua respondendo o resultado original.

422

{
  "type": "https://app.apogeu.ia.br/developers/erros#idempotency-key-reuse",
  "title": "Idempotency-Key reutilizada com outro corpo",
  "status": 422
}

409 · idempotency-in-flight

Requisição idêntica em andamento

type: https://app.apogeu.ia.br/developers/erros#idempotency-in-flight
Quando ocorre: Uma requisição idêntica (mesma chave ou, no MCP, mesmos argumentos) ainda está sendo executada, ou terminou sem gravar a resposta.
Retentar?: Sim, após alguns segundos; se persistir, consulte o recurso antes de repetir — a escrita pode já ter acontecido.

409

{
  "type": "https://app.apogeu.ia.br/developers/erros#idempotency-in-flight",
  "title": "Requisição idêntica em andamento",
  "status": 409
}

409 · estado-invalido

O estado atual não permite a operação

type: https://app.apogeu.ia.br/developers/erros#estado-invalido
Quando ocorre: O pedido está bem formado, mas o estado atual impede a operação. Do registro: audiência, compromisso ou tarefa já encerrados ou alterados por outra pessoa no meio da edição, audiência repetida no mesmo dia e horário, mensagem que já está saindo. Do escritório: cadastro incompleto para gerar documentos, WhatsApp ou assinatura eletrônica desligados, documento com campos em branco ou petição (que não vai para assinatura). O detail diz o que aconteceu e o que fazer.
Retentar?: Sim, depois de resolver o que o detail aponta: consultar o registro de novo ou ajustar a configuração na tela do Apogeu. Repetir sem mudar nada devolve o mesmo erro.

409

{
  "type": "https://app.apogeu.ia.br/developers/erros#estado-invalido",
  "title": "O estado atual não permite a operação",
  "status": 409
}