Fehlerbehandlung

Die API nutzt die üblichen HTTP-Statuscodes. Erfolgreiche Antworten geben den Ressourcenkörper direkt zurück. Fehler folgen RFC 9457 Problem Details for HTTP APIs (application/problem+json) mit zwei Erweiterungsfeldern: einem code auf oberster Ebene, auf den Sie programmatisch verzweigen, und einem field auf oberster Ebene (snake_case) bei Validierungsfehlern eines einzelnen Feldes. Schlagen mehrere Felder gleichzeitig fehl, tritt an die Stelle von field ein Array errors[] (ein Paymos-Erweiterungsfeld, §3.2) mit der Aufschlüsselung je Feld.

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Jede Fehlerantwort folgt RFC 9457 Problem Details for HTTP APIs und wird als Content-Type: application/problem+json ausgeliefert.

Einzelner Fehler (die meisten Antworten)

{
  "type": "https://paymos.io/docs/errors/codes#insufficient_balance",
  "title": "Conflict",
  "status": 409,
  "detail": "Merchant balance is insufficient.",
  "code": "insufficient_balance"
}

Validierung mehrerer Felder

Wird nur gesendet, wenn mehrere Felder gleichzeitig die Prüfung nicht bestehen. Der code auf oberster Ebene ist dann immer validation_failed; die Details je Feld stehen in errors[]:

{
  "type": "https://paymos.io/docs/errors/codes#validation_failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    { "code": "field_required", "field": "currency", "message": "Currency is required." },
    { "code": "field_must_be_positive", "field": "amount", "message": "Amount must be > 0." }
  ]
}

Referenz der Felder

Warum strukturierte Codes und nicht nur message

Der Text von message und detail kann sich zwischen Versionen weiterentwickeln, lokalisiert oder um Kontext ergänzt werden. code ist der stabile Vertrag — ist ein Code einmal veröffentlicht, ändert sich seine Bedeutung nie. Verzweigen Sie für die programmatische Behandlung und die Lokalisierung auf code.

import { RateLimitError, ValidationError } from '@paymos/sdk';

try {
  await paymos.withdrawals.create(request);
} catch (error) {
  if (error instanceof ValidationError) {
    for (const item of error.errors) highlight(item.field, item.message);
  } else if (error instanceof RateLimitError) {
    scheduleRetry(error.retryAfterSeconds);
  }
  throw error;
}

use paymos::{ApiErrorKind, Error};

match paymos.withdrawals().create(&request).await {
    Ok(withdrawal) => process(withdrawal),
    Err(Error::Api(error)) if error.kind == ApiErrorKind::Validation => {
        for item in &error.errors {
            highlight(item.field.as_deref(), &item.message);
        }
    }
    Err(Error::Api(error)) if error.kind == ApiErrorKind::RateLimit => {
        schedule_retry(error.retry_after);
    }
    Err(error) => return Err(error),
}

Fehlerarten

Jeder Status kommt im Fehlerumschlag mit einem title und einem maschinenlesbaren code. Ein Status kann mehrere Fälle abdecken — verzweigen Sie auf den code, nicht auf den Status.

Steuern Sie die Logik Ihres Clients immer über code, nicht über den HTTP-Status — mehrere fachlich verschiedene Fälle teilen sich einen HTTP-Status, und erst der Code auf der Leitung unterscheidet sie.

Anfragegrenzen

Die API erlaubt standardmäßig 30 Anfragen pro Sekunde je Händler, mit einer strengeren Grenze für POST /v1/invoices (5 Anfragen/Sekunde). Gezählt wird je Händler und je Ein-Sekunden-Fenster — alle Ihre API-Schlüssel schöpfen aus demselben Budget —, und beide Grenzen sind je Händler konfigurierbar. Wird die Grenze überschritten, erhalten Sie eine Antwort 429 Too Many Requests mit dem Header Retry-After: 1.

{
  "type": "https://paymos.io/docs/errors/codes#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded (30 req/sec). Retry after 1 second.",
  "code": "rate_limited"
}