Die NueForm-API verwendet die üblichen HTTP-Statuscodes und gibt strukturierte JSON-Fehlerantworten zurück. Diese Anleitung behandelt das Antwortformat, alle möglichen Fehlercodes und Muster für die Fehlerbehandlung in deinem Code.
Antwortformate
Erfolgsantworten
Erfolgreiche API-Aufrufe geben ein JSON-Objekt mit einem data-Feld zurück. Listen-Endpunkte enthalten zusätzlich ein meta-Feld mit Paginierungsinformationen.
{
"data": {
"id": "clx1abc2d3e4f5g6h7i8j9k0",
"title": "Customer Feedback",
"status": "published",
"created_at": "2026-01-15T09:30:00.000Z"
}
}
Mit Paginierungs-Metadaten:
{
"data": [
{
"id": "clx1abc2d3e4f5g6h7i8j9k0",
"title": "Customer Feedback"
},
{
"id": "clx2def3g4h5i6j7k8l9m0n1",
"title": "Employee Survey"
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 150,
"total_pages": 8
}
}
Fehlerantworten
Fehlerantworten geben ein JSON-Objekt mit einem error-Feld zurück, das den Fehler-code, eine menschenlesbare message und den HTTP-status-Code enthält.
{
"error": {
"code": "NOT_FOUND",
"message": "The requested form could not be found.",
"status": 404
}
}
Fehlercodes
Die folgende Tabelle listet alle Fehlercodes auf, die die API zurückgibt:
| Code | HTTP-Status | Beschreibung |
|---|---|---|
BAD_REQUEST | 400 | Die Anfrage ist fehlerhaft, es fehlen Pflichtfelder oder sie enthält ungültige Werte. |
UNAUTHORIZED | 401 | Die Authentifizierung ist fehlgeschlagen. Der API-Schlüssel fehlt, ist fehlerhaft, widerrufen oder abgelaufen. |
FORBIDDEN | 403 | Der authentifizierte Benutzer hat keine Berechtigung für diese Aktion. |
NOT_FOUND | 404 | Die angeforderte Ressource existiert nicht oder ist für den authentifizierten Benutzer nicht zugänglich. |
CONFLICT | 409 | Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource (z. B. doppelter Eintrag). |
RATE_LIMITED | 429 | Zu viele Anfragen. Details findest du unter Rate Limits. |
INTERNAL_ERROR | 500 | Auf dem Server ist ein unerwarteter Fehler aufgetreten. |
Beispiele für Fehlerantworten
400 Bad Request
Wird zurückgegeben, wenn der Anfrage-Body ungültig ist oder Pflichtfelder fehlen.
{
"error": {
"code": "BAD_REQUEST",
"message": "Field 'title' is required.",
"status": 400
}
}
401 Unauthorized
Wird zurückgegeben, wenn die Authentifizierung aus irgendeinem Grund fehlschlägt.
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired API key.",
"status": 401
}
}
403 Forbidden
Wird zurückgegeben, wenn der Benutzer zwar authentifiziert ist, aber keine Berechtigung hat. Häufige Ursachen sind der Zugriff auf Ressourcen eines anderen Benutzers oder die Nutzung einer Funktion, die im aktuellen Tarif nicht enthalten ist.
{
"error": {
"code": "FORBIDDEN",
"message": "API access is not available on your current plan.",
"status": 403
}
}
404 Not Found
Wird zurückgegeben, wenn die angeforderte Ressource nicht existiert.
{
"error": {
"code": "NOT_FOUND",
"message": "The requested form could not be found.",
"status": 404
}
}
409 Conflict
Wird zurückgegeben, wenn die Anfrage ein Duplikat erzeugen würde oder mit vorhandenen Daten in Konflikt steht.
{
"error": {
"code": "CONFLICT",
"message": "A form with this slug already exists.",
"status": 409
}
}
429 Rate Limited
Wird zurückgegeben, wenn das Rate Limit überschritten wurde. Enthält einen Retry-After-Header.
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Please try again later.",
"status": 429
}
}
500 Internal Error
Wird zurückgegeben, wenn ein unerwarteter Serverfehler auftritt. Wenn das Problem bestehen bleibt, wende dich an den Support.
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An internal error occurred.",
"status": 500
}
}
Fehler im Code behandeln
JavaScript
Baue einen wiederverwendbaren API-Client, der auf Fehler prüft und typisierte Exceptions wirft:
class NueFormApiError extends Error {
constructor(code, message, status) {
super(message);
this.name = "NueFormApiError";
this.code = code;
this.status = status;
}
}
async function nueformRequest(path, options = {}) {
const response = await fetch(`https://app.nueform.com/api/v1${path}`, {
...options,
headers: {
"Authorization": `Bearer ${process.env.NUEFORM_API_KEY}`,
"Content-Type": "application/json",
...options.headers,
},
});
const body = await response.json();
if (!response.ok) {
const { code, message, status } = body.error;
throw new NueFormApiError(code, message, status);
}
return body;
}
// Usage
async function getForm(formId) {
try {
const { data } = await nueformRequest(`/forms/${formId}`);
return data;
} catch (error) {
if (error instanceof NueFormApiError) {
switch (error.code) {
case "NOT_FOUND":
console.error(`Form ${formId} does not exist.`);
return null;
case "UNAUTHORIZED":
console.error("Check your API key configuration.");
break;
case "RATE_LIMITED":
console.warn("Rate limited. Implement backoff and retry.");
break;
default:
console.error(`API error [${error.code}]: ${error.message}`);
}
}
throw error;
}
}
Python
import os
import requests
class NueFormApiError(Exception):
def __init__(self, code, message, status):
super().__init__(message)
self.code = code
self.status = status
class NueFormClient:
def __init__(self, api_key=None):
self.api_key = api_key or os.environ["NUEFORM_API_KEY"]
self.base_url = "https://app.nueform.com/api/v1"
def request(self, method, path, **kwargs):
url = f"{self.base_url}{path}"
headers = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
}
response = requests.request(method, url, headers=headers, **kwargs)
body = response.json()
if not response.ok:
error = body["error"]
raise NueFormApiError(
error["code"], error["message"], error["status"]
)
return body
# Usage
client = NueFormClient()
try:
result = client.request("GET", f"/forms/{form_id}")
form = result["data"]
print(f"Form: {form['title']}")
except NueFormApiError as e:
if e.code == "NOT_FOUND":
print(f"Form {form_id} does not exist.")
elif e.code == "UNAUTHORIZED":
print("Check your API key configuration.")
elif e.code == "RATE_LIMITED":
print("Rate limited. Implement backoff and retry.")
else:
print(f"API error [{e.code}]: {e}")
Best Practices
Prüfe immer das error-Feld
Gehe niemals allein aufgrund eines vorhandenen Bodys davon aus, dass eine Antwort erfolgreich war. Prüfe immer auf das error-Feld oder den HTTP-Statuscode, bevor du die Antwort weiterverarbeitest.
Nutze konkrete Fehlercodes für die Ablaufsteuerung
Werte error.code aus (z. B. NOT_FOUND, RATE_LIMITED) statt des HTTP-Statuscodes. Fehlercodes sind stabil, aussagekräftig und in der Anwendungslogik leichter nachzuvollziehen.
Protokolliere Fehlerdetails
Nimm die vollständige Fehlerantwort zum Debuggen in deine Logs auf. code, message und status liefern zusammen genug Kontext, um die meisten Probleme zu diagnostizieren, ohne die Anfrage reproduzieren zu müssen.
Behandle 5xx-Fehler mit Retries
Serverfehler (500 Internal Error) sind in der Regel vorübergehend. Implementiere für diese Antworten eine Retry-Logik mit exponentiellem Backoff. Begrenze die Wiederholungen auf 2--3 Versuche, bevor du abbrichst.
Zeige Fehlermeldungen nicht den Endnutzern
API-Fehlermeldungen richten sich an Entwickler, nicht an Endnutzer. Übersetze API-Fehler in deiner Anwendung in nutzerfreundliche Meldungen.
Wenn du dauerhaft 500 Internal Error-Antworten erhältst, wende dich bitte mit den Anfragedetails und Zeitstempeln an den Support. Serverfehler werden bei uns protokolliert und untersucht.