Error Handling

The ANKK Public API returns standard HTTP status codes accompanied by detailed error JSON bodies.

📌 Standard Error Schema

All error responses adhere to the following schema:

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

🚦 HTTP Status Code Reference

Status Code	Error Code	Meaning & Recommended Action
`400 Bad Request`	`invalid_input`, `validation_failed`	Malformed request body or parameters. Fix payload.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Missing or invalid API key.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Missing scope or plan quota exceeded.
`404 Not Found`	`not_found`	Resource (`content_id`, `connection_id`) not found.
`409 Conflict`	`idempotency_conflict`	Idempotency key reused with mismatched payload.
`423 Locked`	`brand_locked`	Brand locked due to billing or policy. Check Billing.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off per `Retry-After`.
`500 Server Error`	`internal_server_error`	Internal server issue. Retriable with backoff.
`503 Service Unavailable`	`sns_provider_unavailable`	External social network outage. Retriable later.

🔍 Common Business Error Examples

1. 403 Insufficient Scope

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

2. 409 Idempotency Conflict

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

3. 400 Media Validation Failed

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

🔁 Safe Retry Strategies

Retriable (5xx, Network Timeouts): Resend using the exact same idempotency_key with exponential jitter backoff.
Non-Retriable (400, 401, 403, 404, 409): Modify client code or payload, then reissue under a new idempotency key.