Erros

Todas as respostas de erro da Orders API incluem um objeto error. Quando aplicável, também incluem requestId.

Formato

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid order payload.",
    "details": [],
    "requestId": "01HX..."
  }
}

O header X-Request-Id também é enviado em erros.

Código	Status	Significado
`MALFORMED_JSON`	`400`	O corpo não é JSON válido.
`VALIDATION_FAILED`	`400`	Payload ou query params inválidos.
`UNAUTHORIZED`	`401`	Token ausente ou inválido.
`TOKEN_REVOKED`	`403`	Token revogado.
`ORDER_NOT_FOUND`	`404`	Pedido não existe no dashboard autenticado.
`DUPLICATE_EXTERNAL_ID`	`409`	Já existe pedido com esse `externalId`.
`INVALID_STATUS_TRANSITION`	`422`	Mudança de status não permitida.
`RATE_LIMIT_EXCEEDED`	`429`	Limite por token atingido.
`INTERNAL_ERROR`	`500`	Erro inesperado.

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order not found.",
    "requestId": "01HX..."
  }
}

Pedidos de outro dashboard também retornam 404 ORDER_NOT_FOUND, não 403, para reduzir enumeração.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "requestId": "01HX..."
  }
}

Quando houver Retry-After, respeite o tempo antes de reenviar.