Manejo de errores

La API pública de ANKK devuelve códigos de estado HTTP estándar acompañados de cuerpos JSON de error detallados.

📌 Esquema de error estándar

Todas las respuestas de error se ajustan al siguiente esquema:

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

🚦 Referencia de códigos de estado HTTP

Código de estado	Código de error	Significado y acción recomendada
`400 Bad Request`	`invalid_input`, `validation_failed`	Cuerpo de solicitud o parámetros mal formados. Corrija el payload.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Clave de API faltante o no válida.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Alcance faltante o cuota de plan excedida.
`404 Not Found`	`not_found`	Recurso (`content_id`, `connection_id`) no encontrado.
`409 Conflict`	`idempotency_conflict`	Clave de idempotencia reutilizada con un payload que no coincide.
`423 Locked`	`brand_locked`	Marca bloqueada debido a facturación o políticas. Consulte Facturación.
`429 Too Many Requests`	`rate_limited`	Límite de frecuencia excedido. Reintente después del tiempo indicado en `Retry-After`.
`500 Server Error`	`internal_server_error`	Problema interno del servidor. Vuelva a intentarlo con espera exponencial.
`503 Service Unavailable`	`sns_provider_unavailable`	Interrupción de la red social externa. Vuelva a intentarlo más tarde.

🔍 Ejemplos de errores de negocio comunes

1. 403 Alcance insuficiente

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

2. 409 Conflicto de idempotencia

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

3. 400 Error de validación de archivos multimedia

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

🔁 Estrategias de reintento seguras

Se puede reintentar (5xx, tiempos de espera de red): Reenvíe la solicitud con exactamente la misma idempotency_key, aplicando una espera exponencial con variación aleatoria.
No se puede reintentar (400, 401, 403, 404, 409): Corrija el código del cliente o el payload y envíe una solicitud nueva con otra clave de idempotencia.

🔗 Documentación relacionada