Erros

Toda resposta de erro da API da Aeses tem o mesmo formato. Faça branching pelos campos type e code — não pela message, que é legível por humanos e pode mudar.

Formato da resposta

Resposta de erro

{
"error": {
  "type": "invalid_request_error",
  "code": "insufficient_balance",
  "message": "Available USDC balance is 12.50 — requested 50.00.",
  "param": "amount",
  "request_id": "req_01HXYZ7M2P5RT4VG3K8AQWE9FN",
  "doc_url": "https://docs.aeses.io/errors#insufficient_balance"
}
}

| Campo | Sempre presente | Descrição | | ------------ | ---------------- | ----------------------------------------------------------------- | | type | Sim | Categoria de alto nível. Use para decidir comportamento de retry. | | code | Sim | Código estável, legível por máquina. Use para lógica de branch. | | message | Sim | Texto em inglês legível por humanos. Não é estável — não parsei. | | param | Quando aplicável | Parâmetro da requisição que causou o erro. | | request_id | Sim | Devolvido em toda resposta. Inclua ao contatar o suporte. | | doc_url | Quando aplicável | Link direto para a documentação deste código. |

Tipos de erro

| Tipo | HTTP | Refazer? | Significado | | ----------------------- | ----- | ------------------------------ | ---------------------------------------------------------- | | authentication_error | 401 | Nunca — corrija a chave antes. | Chave da API ausente, inválida ou revogada. | | forbidden | 403 | Nunca. | Chave válida mas sem permissão para este recurso. | | invalid_request_error | 400 | Nunca — corrija o payload. | Violação de validação, schema ou regra de negócio. | | not_found | 404 | Nunca. | O recurso solicitado não existe. | | idempotency_error | 409 | Nunca — gere uma chave nova. | Chave de idempotência reutilizada com corpo diferente. | | rate_limit_error | 429 | Sim, com backoff. | Requisições demais. Respeite Retry-After. | | api_error | 500 | Sim, com backoff. | Erro interno do servidor. | | service_unavailable | 503 | Sim, com backoff. | Indisponibilidade temporária. Refaça após uma pausa curta. |

Estratégia de retentativas

Nunca refaça em erros 4xx, exceto 429.
Refaça com backoff exponencial em 429, 500 e 503. Comece em 500ms, dobre até 8s e desista após 5 tentativas.
Envie sempre a mesma Idempotency-Key em cada retentativa para a operação rodar no máximo uma vez. Veja Idempotência.

Códigos de erro comuns

| Código | Tipo | Descrição | | ----------------------------- | ----------------------- | ------------------------------------------------------------------- | | api_key_missing | authentication_error | Header x-api-key ausente. | | api_key_invalid | authentication_error | A chave não existe ou foi revogada. | | key_environment_mismatch | authentication_error | Chave de teste usada em modo live (ou vice-versa). | | parameter_missing | invalid_request_error | Um parâmetro obrigatório foi omitido. param indica qual. | | parameter_invalid | invalid_request_error | Um parâmetro tem tipo ou formato errado. | | unsupported_asset | invalid_request_error | A combinação asset/chain solicitada não é suportada. | | insufficient_balance | invalid_request_error | A conta não tem saldo suficiente para a operação. | | withdrawal_below_minimum | invalid_request_error | O valor do saque está abaixo do mínimo da rede. | | invalid_destination_address | invalid_request_error | O endereço de destino é malformado ou inválido para a rede. | | idempotency_key_reused | idempotency_error | A Idempotency-Key foi usada com um corpo de requisição diferente. | | rate_limited | rate_limit_error | Requisições demais na janela. Honre o Retry-After. | | internal_error | api_error | Falha inesperada no servidor. Seguro refazer. |

Sempre logue o `request_id`