Fehler

Jede Non-2xx-Response von /api/v1 verwendet dasselbe JSON-Format:

json

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

Behandle error.code als stabilen maschinenlesbaren Wert. error.message enthält menschenlesbaren Kontext und gegebenenfalls Details zur Validierung.

Error-Referenz

Status	Code	Bedeutung	Retry?
400	`invalid_request`	Body, Parameter, Cursor oder erforderliche Header sind ungültig.	Request korrigieren.
401	`unauthorized`	Der API-Key fehlt, ist ungültig, abgelaufen oder widerrufen.	Gültigen API-Key verwenden.
403	`forbidden`	Dem API-Key fehlt ein Scope oder der Teamrolle eine Berechtigung.	Zugriff ändern.
403	`plan_required`	Das Team hat derzeit keinen Public-API-Zugang.	Pro-Zugang aktivieren.
404	`not_found`	Die Datei existiert nicht oder gehört zu einem anderen Team.	Nein.
413	`payload_too_large`	Der Direct Upload überschreitet 100 MiB.	Über die App hochladen.
415	`unsupported_media_type`	Der normalisierte Content-Type wird nicht akzeptiert.	Datei oder Typ ändern.
429	`rate_limited`	Das Request-Budget des API-Keys ist aufgebraucht.	`Retry-After` abwarten.
507	`quota_exceeded`	Das Speicherkontingent des Teams ist voll.	Speicher freigeben oder Kontingent erhöhen.
500	`internal_error`	Ein unerwarteter Serverfehler ist aufgetreten.	Mit Backoff wiederholen.

JavaScript-Hilfsfunktion

async function apiFetch(path, options = {}) {
  const response = await fetch(`${process.env.NEW_ARCHIVE_URL}${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.NEW_ARCHIVE_API_KEY}`,
      ...options.headers,
    },
  })

  const body = await response.json()
  if (!response.ok) {
    const error = new Error(body.error?.message ?? `HTTP ${response.status}`)
    error.code = body.error?.code
    error.status = response.status
    error.retryAfter = Number(response.headers.get("retry-after") ?? 0)
    throw error
  }
  return body
}

Rate Limits behandeln

Beachte Retry-After, wenn der Header vorhanden ist. Verwende einen Fallback-Wert und begrenze die Retries, damit eine fehlerhafte Integration nicht endlos Requests sendet.

Validation Errors

Validation Errors benennen das Feld in message. Sie dürfen geloggt werden, der Header Authorization jedoch nicht.

json

{
  "error": {
    "code": "invalid_request",
    "message": "limit: Too big: expected number to be <=100"
  }
}

ZurückUpload-Limits