Błędy API i sposoby ich obsługi

Używaj stałych kodów błędów, aby zdecydować o poprawieniu żądania, odczekaniu lub ponowieniu.

Co zrobić

Podejmuj decyzje na podstawie statusu HTTP i error.code, a nie opisu error.message.
Status 401 wymaga poprawnego uwierzytelnienia, 403 — odpowiedniego dostępu lub planu, a 409 — sprawdzenia kolidującej operacji lub wersji zasobu.

Odmowa dostępu i ponawianie

401: 401 nie zawsze oznacza wygaśnięcie tokenu. Jeśli token wygasł, pobierz nowy i ponów odczyt najwyżej raz. Jeśli pobranie tokenu zwraca 401, sprawdź klucz i przerwij automatyczne próby.
403: Przy 403 sprawdź uprawnienia, ograniczenia IP i plan. Pobranie nowego tokenu nie przywraca odebranego dostępu.

Uwierzytelnianie API

Zasady ponawiania

Błędy przejściowe ponawiaj ograniczoną liczbę razy, zwiększając i losowo różnicując opóźnienia.
Respektuj Retry-After, gdy występuje.
Po przekroczeniu czasu zapisu jego wynik może być nieznany: ponawiając tę samą operację, zachowaj Idempotency-Key i niezmienione żądanie.
Poniższy katalog opisuje każdy opublikowany kod błędu.

Bezpieczny zapis

Limity zapytań

422 / 409

Dla cen nieprawidłowy format waluty lub precyzja kwoty powodują 422 request.validation_failed.
Poprawny kod waluty niezgodny z wybranym cennikiem powoduje 409 resource.version_conflict.
Przed ponowieniem sprawdź kontekst i wersje.

Katalog błędów

400request.malformedNie można odczytać struktury żądania.

Co zrobić: Sprawdź składnię JSON, kodowanie URL i strukturę żądania.
Zasady ponawiania: Ponów po poprawieniu żądania.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsKlucz API lub token jest nieprawidłowy, wygasł albo został unieważniony.

Co zrobić: Sprawdź adres sklepu i dane uwierzytelniające. Pobierz nowy token przy użyciu aktywnego klucza API.
Zasady ponawiania: Ponów po poprawieniu uwierzytelniania; unikaj wielokrotnego wysyłania błędnych danych.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredBrakuje wymaganego nagłówka Authorization albo jego schemat jest nieprawidłowy.

Co zrobić: Przy pobieraniu tokenu użyj ApiKey, a przy operacjach na zasobach — Bearer.
Zasady ponawiania: Ponów po podaniu prawidłowego nagłówka.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedUsługa nie mogła wiarygodnie ustalić adresu IP klienta.

Co zrobić: Poproś operatora sklepu o sprawdzenie drogi połączenia. Nie dodawaj samodzielnie nagłówków przekazywania adresu.
Zasady ponawiania: Ponów po przywróceniu zaufanej drogi połączenia.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedAdres źródłowy nie znajduje się na liście adresów dozwolonych dla klucza.

Co zrobić: Użyj zatwierdzonego adresu źródłowego lub poproś uprawnionego administratora o edycję listy IP klucza.
Zasady ponawiania: Ponów dopiero po dopuszczeniu adresu.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedKlucz nie ma skutecznego uprawnienia wymaganego do tej operacji.

Co zrobić: Sprawdź wymagane i warunkowe uprawnienia operacji, uprawnienia klucza oraz dostęp jego wystawcy.
Zasady ponawiania: Ponów po nadaniu wymaganego dostępu przez uprawnionego administratora.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledDostęp do API jest wyłączony dla tego sklepu.

Co zrobić: Poproś właściciela o sprawdzenie aktywnego planu i dostępności API.
Zasady ponawiania: Nie ponawiaj, dopóki dostęp do API nie zostanie włączony.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededZmiana przekroczyłaby limit bieżącego planu.

Co zrobić: Sprawdź limit danego zasobu i dostosuj planowaną zmianę lub plan sklepu.
Zasady ponawiania: Ponów po rozwiązaniu ograniczenia; użyj nowego klucza idempotencji, jeśli zmienisz żądanie.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledBieżący plan nie obejmuje tej operacji.

Co zrobić: Sprawdź minimalny plan podany dla operacji.
Zasady ponawiania: Ponów, gdy plan pozwala na operację i klucz ma wymagane uprawnienia.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedLimit planu blokuje ten konkretny zasób.

Co zrobić: Poproś właściciela o rozwiązanie ograniczenia planu dotyczącego zasobu.
Zasady ponawiania: Nie powtarzaj tego samego żądania, dopóki zasób pozostaje zablokowany.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundZasób nie istnieje, został usunięty albo nie jest dostępny pod podanym identyfikatorem.

Co zrobić: Sprawdź sklep, ścieżkę zasobu i identyfikator. Używaj identyfikatorów zwróconych przez ten sklep.
Zasady ponawiania: Ponów dopiero po poprawieniu celu lub potwierdzeniu jego istnienia.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedEndpoint nie obsługuje tej metody HTTP.

Co zrobić: Użyj udokumentowanej metody; nagłówek Allow wskazuje obsługiwane metody.
Zasady ponawiania: Nie ponawiaj nieobsługiwanej metody.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedTen klucz idempotencji należy do innego żądania.

Co zrobić: Odszukaj pierwotną operację. Nowego klucza użyj wyłącznie dla świadomie nowej operacji logicznej.
Zasady ponawiania: Nie ponawiaj zmienionej treści z kolidującym kluczem.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsUnikalna wartość koliduje z istniejącym zasobem.

Co zrobić: Odczytaj istniejący zasób i zdecyduj, czy go użyć, czy wybrać inną unikalną wartość.
Zasady ponawiania: Nie powtarzaj tego samego kolidującego tworzenia.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useInne zasoby nadal korzystają z tego zasobu.

Co zrobić: Sprawdź zależności i przed usunięciem usuń je lub zmień za pomocą obsługiwanych operacji.
Zasady ponawiania: Ponów po rozwiązaniu zależności.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictBieżący stan biznesowy uniemożliwia tę zmianę.

Co zrobić: Odczytaj aktualny stan i wybierz poprawną zmianę biznesową.
Zasady ponawiania: Nie wymuszaj automatycznie ani nie wysyłaj wielokrotnie kolidującej zmiany.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictInny zapis zmienił zasób po odczytaniu użytej wersji.

Co zrobić: Pobierz aktualny stan, uzgodnij swoją zmianę i prześlij nową wartość expected_version.
Zasady ponawiania: Użyj nowego klucza idempotencji dla poprawionej operacji; nie nadpisuj danych bez sprawdzenia.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeŻądanie przekracza limit rozmiaru.

Co zrobić: Zmniejsz treść lub podziel pracę na obsługiwane pojedyncze operacje.
Zasady ponawiania: Ponów mniejsze, poprawne operacje z ich własnymi kluczami idempotencji.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeTyp treści lub jej kodowanie nie są obsługiwane.

Co zrobić: Przy zapisie JSON użyj Content-Type: application/json i obsługiwanej nieskompresowanej treści.
Zasady ponawiania: Ponów po poprawieniu typu lub kodowania treści.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedCo najmniej jedno pole lub parametr nie przechodzi walidacji.

Co zrobić: Sprawdź error.fields, a następnie wymagane pola, dopuszczalność null, identyfikatory i dozwolone wartości.
Zasady ponawiania: Ponów poprawione żądanie; zmieniony zapis jest nową operacją logiczną.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullKrótka kolejka API jest pełna; żądanie nie rozpoczęło wykonania.

Co zrobić: Kolejkuj żądania i respektuj nagłówek odpowiedzi Retry-After.
Zasady ponawiania: Odczekaj co najmniej Retry-After sekund i dodaj losowe opóźnienie. Ponawiając zapis, zachowaj oryginalny klucz i treść.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutUpłynął czas oczekiwania w kolejce API; żądanie nie rozpoczęło wykonania.

Co zrobić: Kolejkuj żądania i respektuj nagłówek odpowiedzi Retry-After.
Zasady ponawiania: Odczekaj co najmniej Retry-After sekund i dodaj losowe opóźnienie. Ponawiając zapis, zachowaj oryginalny klucz i treść.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededCzęstotliwość żądań przekracza obowiązujący limit.

Co zrobić: Kolejkuj żądania i respektuj nagłówek odpowiedzi Retry-After.
Zasady ponawiania: Odczekaj co najmniej Retry-After sekund i dodaj losowe opóźnienie. Ponawiając zapis, zachowaj oryginalny klucz i treść.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorWystąpił nieoczekiwany błąd usługi.

Co zrobić: Zapisz identyfikator żądania i skontaktuj się z operatorem, jeśli błąd się powtarza; nie zapisuj danych uwierzytelniających w logach.
Zasady ponawiania: Stosuj ograniczone ponawianie z opóźnieniem. Dla zapisu zachowaj oryginalny klucz idempotencji i niezmienioną treść.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseBrama nie otrzymała prawidłowej odpowiedzi API.

Co zrobić: Zachowaj identyfikator żądania. Błąd odpowiedzi nie dowodzi, że zapis nie został wykonany.
Zasady ponawiania: Stosuj ograniczone ponawianie z opóźnieniem; tę samą operację zapisu ponawiaj z oryginalnym Idempotency-Key i treścią.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI tymczasowo nie może obsłużyć żądania.

Co zrobić: Respektuj Retry-After, jeśli występuje, i zachowaj identyfikator żądania, jeśli awaria się utrzymuje.
Zasady ponawiania: Stosuj ograniczone ponawianie z losowym opóźnieniem; przy ponawianiu tego samego zapisu zachowaj klucz i treść.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutBrama przekroczyła czas oczekiwania na API.

Co zrobić: Zachowaj identyfikator żądania i traktuj wynik zapisu jako nieustalony.
Zasady ponawiania: Stosuj ograniczone ponawianie z opóźnieniem; przy zapisie zachowaj oryginalny klucz idempotencji i niezmienioną treść.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}