Fehlerbehandlung

Die ANKK Public API gibt Standard-HTTP-Statuscodes mit detaillierten JSON-Fehlerantworten zurück.

📌 Standard-Fehlerschema

Alle Fehlerantworten entsprechen dem folgenden Schema:

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

🚦 Referenz der HTTP-Statuscodes

Statuscode	Fehlercode	Bedeutung & Empfohlene Aktion
`400 Bad Request`	`invalid_input`, `validation_failed`	Fehlerhafter Request-Body oder Parameter. Payload korrigieren.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Fehlender oder ungültiger API-Key.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Fehlender Scope oder Plan-Kontingent überschritten.
`404 Not Found`	`not_found`	Ressource (`content_id`, `connection_id`) nicht gefunden.
`409 Conflict`	`idempotency_conflict`	Idempotency-Key mit nicht übereinstimmendem Payload wiederverwendet.
`423 Locked`	`brand_locked`	Marke aufgrund von Abrechnung oder Richtlinien gesperrt. Siehe Abrechnung.
`429 Too Many Requests`	`rate_limited`	Ratenbegrenzung überschritten. Warten gemäß `Retry-After`.
`500 Server Error`	`internal_server_error`	Internes Serverproblem. Die Anfrage kann mit zunehmender Wartezeit wiederholt werden.
`503 Service Unavailable`	`sns_provider_unavailable`	Externer SNS-Dienst nicht verfügbar. Später erneut versuchen.

🔍 Beispiele für häufige Geschäftslogik-Fehler

1. 403 Unzureichender Scope

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

2. 409 Idempotenzkonflikt

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

3. 400 Medienvalidierung fehlgeschlagen

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

🔁 Sichere Wiederholungsstrategien

Wiederholbar (5xx, Netzwerk-Timeouts): Senden Sie die Anfrage mit exakt demselben idempotency_key und exponentiellem Jitter-Backoff erneut.
Nicht wiederholbar (400, 401, 403, 404, 409): Ändern Sie den Client-Code oder den Payload und senden Sie die Anfrage dann unter einem neuen Idempotency-Key erneut.

🔗 Verwandte Dokumentation