{"data":{"external_id":3572,"slug":"api-antworten-und-fehler-verstehen","title":"API-Antworten und Fehler verstehen","content":"Wie eine Antwort der API aufgebaut ist, woran du einen Fehler erkennst und was die einzelnen Fehlertypen bedeuten. Mit diesem Wissen baust du deine Integration robust und findest Probleme schnell.\nAufbau erfolgreicher Antworten\nDie sechs Fehlertypen und ihre Statuscodes\nFehler-Header und die trace_id f\u00fcr den Support\nErfolgreiche Antworten\nNutzdaten liegen immer unter data. Eine einzelne Ressource steht als Objekt darin, eine Liste als Array.\n{\n  \"data\": {\n    \"id\": 10001,\n    \"label\": \"mein-webserver\",\n    \"status\": \"Active\"\n  }\n}\nBei manchen Routen kommen zus\u00e4tzliche Felder wie meta (etwa f\u00fcr Paginierung) oder message (ein erkl\u00e4render Hinweis) dazu. Der data-Umschlag bleibt aber die Konstante, an der du dich orientierst.\nWoran du einen Fehler erkennst\nFehler kommen ohne data-Umschlag. Stattdessen steht das Fehlerobjekt direkt auf oberster Ebene und beginnt immer mit error: true. Drei Felder sind bei jedem Fehler dabei:\nerror: immer true.\ntrace_id: eine eindeutige Kennung f\u00fcr genau diesen Fehler.\ntype: der Fehlertyp, siehe unten.\nmessage: eine kurze, menschenlesbare Beschreibung.\nJe nach Fehlertyp kommen weitere Felder hinzu. Beim fehlenden Best\u00e4tigungstoken sieht das zum Beispiel so aus:\n{\n  \"error\": true,\n  \"trace_id\": \"67d82f94-7a6f-40fe-a49f-6a10d888a52f\",\n  \"type\": \"confirmation_error\",\n  \"message\": \"Confirmation token not found by value.\",\n  \"required_type\": \"reinstall_os\",\n  \"required_id\": \"10001\",\n  \"hint_route\": \"https:\/\/api.pph.systems\/api\/confirmation-token?for=reinstall_os&related_id=10001\"\n}\nWerte deine Fehlerbehandlung immer \u00fcber das Feld type aus, nicht \u00fcber den Text in message. Der Typ ist stabil, die Formulierung der Nachricht kann sich \u00e4ndern.\nDie Fehlertypen im \u00dcberblick\nEs gibt sechs Fehlertypen. Der HTTP-Statuscode dazu ist in der Regel wie folgt.\ntypeStatusBedeutungWas du tun kannstauthentication_error401Token fehlt, ist falsch oder wurde widerrufenToken pr\u00fcfen und korrekt im Authorization-Header sendenaccess_denied403Der Token darf diese Route nicht nutzenBerechtigungen des Tokens pr\u00fcfen, Gated Routes freigebenentity_not_found404Die angefragte Ressource existiert nicht oder geh\u00f6rt dir nichtID pr\u00fcfenvalidation_error422Die Anfrage ist unvollst\u00e4ndig oder ung\u00fcltigFehlende oder falsche Parameter korrigierenconfirmation_error400F\u00fcr eine kritische Aktion fehlt das Best\u00e4tigungstokenToken erzeugen und im X-Confirmation-Token-Header sendengeneral_error500Ein unerwarteter Fehler auf unserer SeiteSp\u00e4ter erneut versuchen, bei anhaltendem Fehler die trace_id an den Support geben\nZwei Beispiele, die dir am Anfang oft begegnen. Bei einer Route, die dein Token nicht nutzen darf:\n{\n  \"error\": true,\n  \"trace_id\": \"1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed\",\n  \"type\": \"access_denied\",\n  \"message\": \"Access to the route vps.status.reboot is denied.\"\n}\nBei einer unvollst\u00e4ndigen Anfrage:\n{\n  \"error\": true,\n  \"trace_id\": \"3f7c1e02-6a44-4c9a-8f1e-9b2d5c7a0e11\",\n  \"type\": \"validation_error\",\n  \"message\": \"The given data was invalid.\"\n}\nFehler stehen auch in den Headern\nZus\u00e4tzlich zum Body liefert jede Fehlerantwort drei Header. Praktisch, wenn du in einem Skript nur die Header pr\u00fcfen willst, ohne den Body zu parsen.\nX-Error-Type\nX-Error-Message\nX-Error-Trace-Id\nDas ma\u00dfgebliche Feld f\u00fcr deine Logik bleibt type im Body.\nRate-Limit\nJeder Token hat ein Anfragekontingent pro Zeitfenster. Zwei Header zeigen dir bei jeder Antwort deinen Stand:\nX-RateLimit-Limit: dein Kontingent im aktuellen Fenster.\nX-RateLimit-Remaining: wie viele Anfragen dir noch bleiben.\nIst das Kontingent aufgebraucht, antwortet die API mit HTTP 429. Warte in dem Fall kurz und wiederhole die Anfrage. Baue in automatisierten Abl\u00e4ufen am besten ein, dass X-RateLimit-Remaining beobachtet wird, bevor es so weit kommt. Mehr dazu steht in Wie ist die API abgesichert?.\nDie trace_id ist dein Draht zum Support\nJede Fehlermeldung enth\u00e4lt eine trace_id. Wir protokollieren Fehler serverseitig, und diese Kennung verbindet deine Fehlermeldung mit unserem Protokoll. Wenn du dich mit einem Problem an uns wendest, gib die trace_id mit an. So finden unsere Entwickler den Vorgang sofort, ohne raten zu m\u00fcssen.\nWie geht es weiter?\nWie du deine erste Anfrage stellst, steht im Quickstart.\nWie du kritische Aktionen freigibst, steht in Kritische Aktionen mit einem Best\u00e4tigungstoken freigeben.\nNoch Fragen?\nTechnische Fragen zur API beantworten dir unsere Entwickler direkt in unserem Discord. Stell deine Frage im Entwickler-Channel und pinge das Dev-Team an.","schema":null,"facts":[],"links":[{"type":"external","url":"https:\/\/support.prepaid-hoster.de\/faq\/de\/api\/wie-ist-die-api-abgesichert.html","data":{"title":"Not Found","meta_description":"","meta":[]}},{"type":"faq","url":"https:\/\/support.prepaid-hoster.de\/faq\/de\/api\/meine-erste-api-anfrage-der-quickstart.html","data":{"post_id":"56860","post_slug":"meine-erste-api-anfrage-der-quickstart","post_cat_id":"24"}},{"type":"faq","url":"https:\/\/support.prepaid-hoster.de\/faq\/de\/api\/kritische-aktionen-mit-einem-bestaetigungstoken-freigeben.html","data":{"post_id":"56861","post_slug":"kritische-aktionen-mit-einem-bestaetigungstoken-freigeben","post_cat_id":"24"}}]}}