Erros — Documentação MandAPI

Formato do erro

As respostas de erro usam o envelope OpenAI. Exemplo real retornado pela API:

{
  "error": {
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error",
    "param": null,
    "code": ""
  }
}

Importante: o campo code vem sempre vazio (""). Para identificar o problema, use o código HTTP e o texto de message.

HTTP	Motivo (PT-BR)	O que fazer
401	Token ausente ou inválido (`Invalid token`).	Confira a API Key e o cabeçalho `Authorization: Bearer …`. A chamada não chega ao modelo.
403	Sem acesso ao modelo informado (`This token has no access to model X`). Inclui modelo inexistente ou sem o campo `model`.	Confirme o `model` em `GET /v1/models` e se a chave tem acesso a ele.
400	Corpo da requisição inválido (`Invalid request: invalid JSON request body`).	Valide o JSON enviado: aspas, vírgulas e tipos dos campos.
404	`bad_response_status_code` — ex.: usar `/v1/embeddings` sem um modelo de embedding configurado.	Confira o endpoint e se o modelo suporta essa capacidade.
429	Limite de requisições atingido TO VERIFY (o middleware de limite existe; o limite exato ainda está em verificação).	Faça retry com backoff. Reduza o ritmo ou distribua as chamadas.
5xx	Erro interno do servidor TO VERIFY (não testado especificamente nesta documentação).	Repita a chamada com backoff. Se persistir, registre o `X-Oneapi-Request-Id` e contate o suporte.

Toda resposta traz um cabeçalho X-Oneapi-Request-Id. Guarde-o ao abrir um chamado de suporte — ele permite rastrear a chamada específica.

Esta página descreve apenas o que foi verificado em produção. Não inventamos códigos ou mensagens que não tenham sido observados na API.

Cada erro tem um guia completo de diagnóstico: guias de erros de API — 401, 404, 429, 500, timeout, JSON inválido e model not found.