Tratamento de erros

A API Pública do ANKK retorna códigos de status HTTP padrão acompanhados por corpos JSON de erro detalhados.

📌 Esquema de Erro Padrão

Todas as respostas de erro seguem o seguinte esquema:

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used with a different request payload.",
  "param": "idempotency_key"
}

🚦 Referência de Códigos de Status HTTP

Código de Status	Código de Erro	Significado e Ação Recomendada
`400 Bad Request`	`invalid_input`, `validation_failed`	Corpo da requisição ou parâmetros malformados. Corrija o payload.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Chave de API ausente ou inválida.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Escopo ausente ou cota do plano excedida.
`404 Not Found`	`not_found`	Recurso (`content_id`, `connection_id`) não encontrado.
`409 Conflict`	`idempotency_conflict`	Chave de idempotência reutilizada com payload incompatível.
`423 Locked`	`brand_locked`	Marca bloqueada devido a faturamento ou política. Verifique Faturamento.
`429 Too Many Requests`	`rate_limited`	Limite de taxa excedido. Aguarde conforme `Retry-After`.
`500 Server Error`	`internal_server_error`	Problema interno do servidor. Tente novamente com backoff.
`503 Service Unavailable`	`sns_provider_unavailable`	Interrupção externa na rede social. Tente novamente mais tarde.

🔍 Exemplos de Erros de Negócio Comuns

1. 403 Escopo insuficiente

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required 'publishing:create' scope."
}

2. 409 Conflito de idempotência

{
  "error": "idempotency_conflict",
  "message": "Idempotency key 'launch-001' is already bound to a different request hash.",
  "param": "idempotency_key"
}

3. 400 Falha na validação de mídia

{
  "error": "sns_content_media_maximum_exceeded",
  "message": "Bluesky supports a maximum of 4 images per post.",
  "param": "media"
}

🔁 Estratégias seguras de nova tentativa

Pode ser repetida (5xx, timeouts de rede): Reenvie a solicitação usando exatamente a mesma idempotency_key, com espera exponencial e variação aleatória.
Não pode ser repetida (400, 401, 403, 404, 409): Corrija o código ou o payload do cliente e envie uma nova solicitação com outra chave de idempotência.

🔗 Documentação Relacionada