Fehlercodes und Fehlerbehebung

Standardisierte HTTP-Fehlerstruktur, Fehlerkatalog und Resilienz-Strategien.

Wenn eine Anfrage nicht erfolgreich verarbeitet werden kann, liefert SmallPict einen HTTP-Statuscode zusammen mit einem strukturierten JSON-Fehlerobjekt zurück.

JSON-Fehlerstruktur

JSON

{  "success": false,  "error": {    "code": "INVALID_IMAGE_PAYLOAD",    "message": "Die übermittelte Datei ist kein gültiges Bild oder beschädigt.",    "details": {      "mime_type": "text/html",      "expected": [        "image/jpeg",        "image/png",        "image/webp",        "image/avif"      ]    }  }}

Übersicht über HTTP-Statuscodes

Code	Fehlerbezeichner	Ursache	Empfohlene Maßnahme
`400`	`BAD_REQUEST`	Ungültiges JSON oder fehlerhafte Parameter.	JSON-Syntax und Parameternamen korrigieren.
`401`	`UNAUTHORIZED`	API-Schlüssel fehlt oder wurde widerrufen.	Header `X-API-Key` überprüfen.
`401`	`TIMESTAMP_DRIFT`	Zeitstempel weicht um mehr als ±300s ab.	Serveruhrzeit via NTP abgleichen.
`401`	`INVALID_SIGNATURE`	Berechnete Signatur stimmt nicht überein.	Kanonische Zeichenkette und Secret Key prüfen.
`403`	`FORBIDDEN`	Schlüssel besitzt keine Berechtigung für diese Ressource.	Berechtigungen im Dashboard anpassen.
`404`	`NOT_FOUND`	Auftrag (`job_id`) oder Ressource existiert nicht.	ID in der URL prüfen.
`413`	`PAYLOAD_TOO_LARGE`	Datei überschreitet die maximale Dateigröße Ihres Tarifs.	Bild vor dem Upload herunterskalieren.
`415`	`UNSUPPORTED_MEDIA`	Nicht unterstützter Dateityp.	Ausschließlich JPEG, PNG, WebP, AVIF oder SVG senden.
`422`	`UNPROCESSABLE`	Datei hat gültige Endung, ist aber korrupt.	Datei-Integrität vor dem Absenden prüfen.
`429`	`RATE_LIMIT_EXCEEDED`	Zu viele Anfragen pro Zeiteinheit.	Exponential Backoff bei Retries implementieren.
`429`	`QUOTA_EXCEEDED`	Monatliches Kontingent vollständig erschöpft.	Tarif im Dashboard erweitern.
`500`	`INTERNAL_ERROR`	Unerwarteter Fehler im Server-Cluster.	Anfrage nach kurzer Wartezeit wiederholen.
`503`	`SERVICE_UNAVAILABLE`	Wartungsfenster oder temporäre Spitzenlast.	Temporär im Passthrough-Modus betreiben.