Zapowiedź

Dokumentacja poglądowa. Interfejs jest w trakcie udostępniania — przykłady mają charakter zapowiedzi, a finalne wartości potwierdzimy przy starcie.

Błędy (Problem Details)

Wszystkie błędy Commerce API v1 zwracamy w formacie application/problem+json (RFC 9457). Dzięki jednolitej strukturze możesz obsłużyć błędy generycznie: najpierw po statusie HTTP, a dokładniej po polu code.

Format odpowiedzi błędu

Pole	Znaczenie
`type`	URI identyfikujący typ problemu
`title`	Krótki, czytelny dla człowieka opis typu błędu
`status`	Kod statusu HTTP (powielony w body)
`code`	Stabilny, maszynowy identyfikator błędu (obsługuj po nim)
`detail`	Opis konkretnego wystąpienia błędu
`instance`	URI/identyfikator tego konkretnego wystąpienia
`correlation_id`	Identyfikator do korelacji ze wsparciem
`errors`	Lista błędów szczegółowych (np. per pole przy walidacji)

Obsługuj błędy po polu code, a nie po treści title/detail — teksty mogą się zmieniać, kody są stabilne w obrębie v1.

Katalog kodów błędów

Status	`code`	Kiedy występuje
401	`invalid_signature`	Podpis nieprawidłowy lub nagłówki niespójne
401	`expired_timestamp`	Znacznik czasu poza oknem replay (300 s)
401	`replay_nonce`	Nonce już użyty w oknie replay dla tego klucza
403	`insufficient_scope`	Klucz nie ma scope wymaganego dla operacji
404	`resource_not_found`	Zasób nie istnieje lub jest niedostępny dla klucza
409	`idempotency_key_reused`	Ten sam `Idempotency-Key` z innym hash body
409	`stale_source_version`	`source_version` starszy niż zapisany
413	`payload_too_large`	Body przekracza dopuszczalny rozmiar
422	`validation_failed`	Body niepoprawne — szczegóły w polu `errors`
429	`rate_limited`	Przekroczony rate limit — patrz nagłówek `Retry-After`
503	`tenant_unavailable`	Chwilowa niedostępność — ponów po `Retry-After`

Statusy 401/403 opisuje bliżej Uwierzytelnianie, a konflikty 409 — Idempotency. Limity i 429/413 znajdziesz w sekcji Paginacja i limity.

Przykładowe body błędu

HTTP/1.1 422 Unprocessable Entity Content-Type: application/problem+json

{ "type": "https://api.callbotagent.ai/problems/validation-failed", "title": "Walidacja nie powiodła się", "status": 422, "code": "validation_failed", "detail": "Pole customer.phone ma nieprawidłowy format.", "instance": "/api/v1/commerce/orders", "correlation_id": "corr_3f9a12c7", "errors": [ { "field": "customer.phone", "code": "invalid_format", "message": "Wymagany format E.164." } ] }

if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  handleByCode(problem.code, problem.correlation_id);
}

if ($response->getStatusCode() >= 400) {
    $problem = json_decode((string) $response->getBody(), true);
    handle_by_code($problem['code'], $problem['correlation_id']);
}

Correlation ID i zgłoszenia do wsparcia

Pole correlation_id jednoznacznie identyfikuje wystąpienie błędu po naszej stronie. Zapisz je w swoich logach i podaj przy kontakcie ze wsparciem — przyspiesza to diagnostykę. Nie umieszczaj w zgłoszeniu sekretu klucza ani danych osobowych klientów; wystarczy correlation_id, code i znacznik czasu.