Erros

Formato padrão

Todos os erros retornam JSON no seguinte formato:

{
  "message": "Mensagem legível do erro",
  "internal_code": "CODIGO_INTERNO",
  "status": 422
}

Códigos HTTP

Status	Significado
400	Bad Request — dados inválidos ou operação não permitida
401	Unauthorized — token ausente ou inválido
403	Forbidden — sem permissão (role insuficiente)
404	Not Found — recurso não encontrado
422	Unprocessable Entity — falha de validação
500	Internal Server Error — erro inesperado

Internal Codes

Autenticação

Código	HTTP	Descrição
UNAUTHORIZED	401	Token JWT ausente, inválido ou expirado
FORBIDDEN	403	Usuário não possui a role necessária

Recursos

Código	HTTP	Descrição
NOT_FOUND	404	Recurso não encontrado
DUPLICATED_ENTRY	422	Registro duplicado (ex: e-mail já cadastrado)
BAD_REQUEST	400	Requisição malformada ou operação inválida
UNPROCESSABLE_ENTITY	422	Falha de validação de campos

Pagamentos

Código	HTTP	Descrição
CARD_NOT_VALID	422	Cartão de crédito recusado ou inválido
PAYMENT_TRANSACTION_DENIED	422	Transação negada pela operadora
PICPAY_TRANSACTION_ERROR	422	Erro ao criar cobrança PicPay
PIX_TRANSACTION_ERROR	422	Erro ao gerar cobrança Pix

Negócio

Código	HTTP	Descrição
COUPON_NOT_VALID	422	Cupom inválido, expirado ou já utilizado
RESTAURANT_CLOSED	422	Restaurante fechado para novos pedidos
INVOICES_OPEN	422	Há comandas abertas impedindo a operação
GEOCODE_ZERO_RESULT	422	Endereço não encontrado no serviço de geocodificação
INTERNAL_ERROR	500	Erro interno inesperado

Exemplos

Token expirado

{
  "message": "Token has expired",
  "internal_code": "UNAUTHORIZED",
  "status": 401
}

Cupom inválido

{
  "message": "Cupom inválido ou expirado",
  "internal_code": "COUPON_NOT_VALID",
  "status": 422
}

Restaurante fechado

{
  "message": "O restaurante está fechado no momento",
  "internal_code": "RESTAURANT_CLOSED",
  "status": 422
}

Cartão recusado

{
  "message": "Cartão não autorizado",
  "internal_code": "PAYMENT_TRANSACTION_DENIED",
  "status": 422
}