Przejdź do treści
ShopentlyLearn

Kody błędów

Jeśli żądanie się nie powiedzie, sprawdź kod błędu w odpowiedzi. Rozwiń go na liście poniżej, aby dowiedzieć się, co się stało i co zrobić dalej. Przy każdym błędzie znajdziesz też przykład odpowiedzi i wskazówki dotyczące ponowienia żądania.

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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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 i anulowaniu tokenu użyj klucza API z oznaczeniem ApiKey w nagłówku Authorization. Do pozostałych żądań używaj tokenu dostępu z oznaczeniem Bearer.
Zasady ponawiania
Ponów po podaniu prawidłowego nagłówka.
Odpowiedź
{
  "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ć
Sprawdź, z jakiego adresu IP Twoja integracja łączy się z API. Jeśli błąd nadal występuje, skontaktuj się z pomocą techniczną Shopently.
Zasady ponawiania
Ponów żądanie po wyjaśnieniu problemu z rozpoznaniem adresu IP.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409storage.limit_reachedWyczerpano miejsce na zdjęcia i pliki sklepu. Zwolnij miejsce lub zwiększ limit.
Co zrobić
Wyczerpano miejsce na zdjęcia i pliki sklepu. Zwolnij miejsce lub zwiększ limit.
Zasady ponawiania
Ponów mniejsze, poprawne operacje z ich własnymi kluczami idempotencji.
Odpowiedź
{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "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.
Odpowiedź
{
  "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.
Odpowiedź
{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

416request.range_not_satisfiableOgraniczenia: Range
Co zrobić
Range: bytes=0-(size_bytes-1)
Zasady ponawiania
Ponów po poprawieniu żądania.
Odpowiedź
{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "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ą.
Odpowiedź
{
  "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 tyle sekund, ile wskazuje nagłówek Retry-After. Jeśli ponawiasz zapis, zachowaj tę samą treść żądania i tę samą wartość Idempotency-Key.
Odpowiedź
{
  "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 tyle sekund, ile wskazuje nagłówek Retry-After. Jeśli ponawiasz zapis, zachowaj tę samą treść żądania i tę samą wartość Idempotency-Key.
Odpowiedź
{
  "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 tyle sekund, ile wskazuje nagłówek Retry-After. Jeśli ponawiasz zapis, zachowaj tę samą treść żądania i tę samą wartość Idempotency-Key.
Odpowiedź
{
  "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ć
Odczekaj chwilę przed ponowieniem żądania. Jeśli błąd 500 pojawi się ponownie, skontaktuj się z pomocą techniczną Shopently. W zgłoszeniu podaj identyfikator żądania.
Zasady ponawiania
Pobieranie danych możesz ponowić po krótkiej przerwie. Przy ponawianiu zapisu użyj tej samej wartości Idempotency-Key i nie zmieniaj treści żądania.
Odpowiedź
{
  "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ą.
Odpowiedź
{
  "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ć
Jeśli w odpowiedzi jest nagłówek Retry-After, odczekaj wskazaną w nim liczbę sekund przed kolejną próbą. Jeśli go nie ma, spróbuj ponownie za chwilę. Gdy błąd się powtarza, skontaktuj się z pomocą techniczną Shopently i podaj identyfikator żądania.
Zasady ponawiania
Ponów żądanie po odczekaniu czasu opisanego wyżej. Przy ponawianiu zapisu użyj tej samej wartości Idempotency-Key i nie zmieniaj treści żądania.
Odpowiedź
{
  "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ć
Jeśli żądanie zmieniało dane, sprawdź, czy zostały zapisane w sklepie. Brak odpowiedzi nie oznacza, że zapis się nie powiódł. Jeśli błąd się powtarza, skontaktuj się z pomocą techniczną Shopently i podaj identyfikator żądania.
Zasady ponawiania
Pobieranie danych możesz ponowić po krótkiej przerwie. Przy ponawianiu zapisu użyj tej samej wartości Idempotency-Key i nie zmieniaj treści żądania.
Odpowiedź
{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}