Erros

Formato

Os erros retornam JSON neste envelope:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "customerPhone obrigatório: pedido sem telefone do destinatário não pode ser criado"
  }
}

• code é o nome do status HTTP em maiúsculas (BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, UNPROCESSABLE_ENTITY, TOO_MANY_REQUESTS).
• message está em português.
• Em erros de validação (400), message junta as falhas separadas por "; " e details traz a lista.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Required; Required",
    "details": ["Required", "Required"]
  }
}

Nota

A exceção é o endpoint de token: credenciais inválidas retornam 401 com Content-Type: application/problem+json e o corpo { "title": "Invalid client credentials", "status": 401 }. Os erros de validação do token (400) usam o envelope acima.

Códigos de status

Status	Quando	Mensagens
400	Corpo inválido ou campo obrigatório ausente	Falhas de validação (details)
401	Autenticação ausente ou inválida	“Token inválido ou expirado”; “Integração Open Delivery não encontrada” (integração inativa ou inexistente); “Assinatura ausente”; “Assinatura inválida”
403	Cancelar sem permissão na loja	“Empresa sem permissão para cancelar pedidos”
404	Entrega inexistente ou de outra integração	“Pedido não encontrado”
409	Cancelar entrega concluída ou em devolução	“Pedido já finalizado”; “Pedido #… está em devolução. Conclua a devolução antes de cancelar.”
422	Criação sem telefone	“customerPhone obrigatório: pedido sem telefone do destinatário não pode ser criado”
422	Loja sem unidade de coleta	“Empresa sem unidade de coleta cadastrada — configure ao menos uma unidade antes de habilitar a integração”
422	Unidade de coleta inativa	“Unidade inativa não pode receber pedidos”
422	Cancelar após a retirada	“O pedido já está a caminho. Abra uma ocorrência para a equipe avaliar o cancelamento.” (fale com a operação da RaptorX)
422	Distância fora das faixas de preço da loja	“Distância de … km fora das faixas da tabela …” (a RaptorX precisa ajustar a tabela)
429	Limite de requisições	“Muitas tentativas. Aguarde um minuto e tente novamente.”
500	Erro interno	“Erro interno do servidor”

Quando você usa https://api.raptorx.com.br e a instância da loja está indisponível, a RaptorX pode responder 502 com { "message": "Gateway de integração indisponível" } (fora do envelope acima). Repita a chamada depois de alguns instantes; a criação de entrega é idempotente por orderId.

Limite de requisições

O limite é de 300 requisições por 60 segundos por endereço IP, contadas por endpoint. Ao excedê-lo, a resposta é 429. Aguarde um minuto e tente novamente.

Boas práticas

• Trate 5xx, 429 e timeouts com nova tentativa e espera crescente. Na criação de entrega, repetir é seguro por causa da idempotência por orderId.
• Não repita automaticamente 400, 401, 403, 404, 409 e 422 sem corrigir a causa. Em 401, obtenha um novo token.