Fehler

Jeder Fehler der API hat dasselbe Format (RFC 9457, Content-Type application/problem+json). Das gilt für alle Fehler: falscher Schlüssel, unbekannter Pfad, falsche Eingabe, zu viele Anfragen und Probleme auf unserer Seite.

{
  "type": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "title": "Missing permission",
  "status": 403,
  "error_type": "permission",
  "code": "insufficient_scope",
  "message": "This key lacks the permission 'contacts:write'.",
  "param": null,
  "retryable": false,
  "doc_url": "https://docs.smartchat.marketing/en/errors#insufficient_scope",
  "request_id": "req_01JAB9C3X7K2M4N5P6Q7R8S9T0",
  "required_scope": "contacts:write"
}

#Felder

Name	Type	Required	Description
`type`	string	yes	URL of the documentation for this error. up to 300 characters
`title`	string	yes	Short title. up to 100 characters
`status`	integer	yes	HTTP status. 400 to 599
`error_type`	string	yes	Stable error class. Branch on this first, then on code. one of: `authentication`, `permission`, `invalid_request`, `conflict`, `rate_limit`, `api`
`instance`	string	no	Path of the request that failed. up to 300 characters
`code`	string	yes	Stable error code from the error catalog. up to 60 characters
`message`	string	yes	English explanation. Contains no personal data. up to 500 characters
`param`	string or null	no	Path of the invalid field, for example body.tags[2]. up to 200 characters
`retryable`	boolean	yes	True if the same request may work later.
`doc_url`	string	yes	Link to the error page. up to 300 characters
`request_id`	string	yes	ID of the request, also in the Request-Id header. up to 40 characters
`errors`	array of object	no	All input errors when more than one field is invalid. up to 50 items
`errors[].param`	string	yes	Path of the field. up to 200 characters
`errors[].code`	string	yes	Error code. up to 60 characters
`errors[].message`	string	yes	English explanation. up to 500 characters

Manche Fehler fügen Felder hinzu, die zu ihnen gehören, zum Beispiel required_scope, existing_id oder limit. Ihre Bedeutung steht beim Code im Fehlerkatalog.

#So gehst du mit einem Fehler um

Sieh zuerst auf error_type. Er ist einer von authentication, permission, invalid_request, conflict, rate_limit oder api. Er ändert sich für einen Code nie.
Dann sieh auf code. Codes sind stabil. Die message ist für Menschen; werte sie nicht automatisch aus.
Ist retryable gleich true, kann dieselbe Anfrage später klappen. Bei rate_limited warte die Sekunden aus Retry-After. Sonst ändere die Anfrage.
Behalte die request_id. Wenn du Hilfe brauchst, schreibe dem Support und nenne sie.

#400 und 422

400: Die Anfrage ist nicht richtig gebaut. Zum Beispiel ist der Body kein JSON, ein Feld fehlt oder ist unbekannt, oder der Cursor ist kaputt.
422: Die Anfrage ist richtig gebaut, aber ihr Inhalt verletzt eine Regel. Zum Beispiel ist eine Telefonnummer ungültig oder der Kontakt hat kein Opt-in.

#Mehrere falsche Felder

Sind mehrere Felder falsch, listet errors alle in einer Antwort auf, jedes mit param, code und message. Der param ist der Pfad des Felds, zum Beispiel body.tags[2].

#Nie ein Fehler, den du nicht verfolgen kannst

Fehlermeldungen enthalten keine persönlichen Daten. Meldet ein verbundener Dienst wie WhatsApp ein Problem, bekommst du upstream_error mit einem kurzen Code, nie den Rohtext des anderen Dienstes.