Błędy
Koperta błędu
Każda odpowiedź inna niż 2xx ma ten sam kształt. Rozgałęziaj po error.code, nigdy po komunikacie. error.details zależy od kodu; przy odmowach dla klucza API zawiera powód (reason).
requestId jest też w nagłówku X-Request-Id każdej odpowiedzi, udanej lub nie. Podaj go, kontaktując się z pomocą.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Kody błędów
400validation_failedTreść lub zapytanie nie przeszły walidacji. details to lista problemów { path, message }.400bad_requestŻądanie jest poprawnie zbudowane, ale nie można go wykonać; details.reason mówi dlaczego.401unauthorizedKlucza brakuje, jest nieprawidłowy, unieważniony lub wygasł.403forbiddenKlucz nie ma do tego uprawnień: brak zakresu (scope), ograniczenie folderu lub IP albo trasa tylko dla aplikacji. Zobacz details.reason.404not_foundNie ma takiego obiektu w tym obszarze roboczym albo klucz go nie widzi.409conflictSlug lub nazwa hosta jest zajęta albo żądanie z tym samym Idempotency-Key nadal trwa.422idempotency_conflictIdempotency-Key został już użyty z inną treścią.410goneObiekt istniał i został usunięty lub zwolniony.413payload_too_largeTreść lub przesłany plik przekracza limit rozmiaru.429rate_limitedPrzekroczono budżet na minutę lub burst obszaru roboczego. Poczekaj Retry-After sekund.403plan_limit_reachedOsiągnięto limit planu (kody, wiersze zbiorcze, zadania…). details podaje limit i zużycie.403feature_not_in_planPlan obszaru roboczego tego nie obejmuje (na przykład webhooków w Free).422unsafe_destinationAdres docelowy nie przeszedł kontroli Google Web Risk i list blokad.500internalCoś zawiodło po naszej stronie. Ponów z backoffem; jeśli problem trwa, podaj requestId.503unavailableChwilowo niedostępne. Ponów z backoffem.Odmowy dla kluczy API
details.reason odmów specyficznych dla kluczy API.
403 forbiddenmissing_scopeKlucz nie ma zakresu trasy (details.scope) albo rola jego twórcy już na to nie pozwala.403 forbiddensession_requiredTrasa jest tylko dla aplikacji (rozliczenia, członkowie, zarządzanie kluczami…); klucze nie mogą jej wywołać.403 forbiddenapi_key_folder_restrictedKlucz jest ograniczony do niektórych folderów (details.folderIds), a żądanie dotyczy innego.403 forbiddenip_not_allowedAdres wywołującego jest poza listą dozwolonych adresów IP klucza.400 bad_requesttest_mode_unavailableKluczy sk_test_ nie można tworzyć: nie ma jeszcze trybu testowego. Do testów użyj osobnego obszaru roboczego.400 bad_requesttoo_many_api_keysObszar roboczy ma już 50 aktywnych kluczy (details.limit). Najpierw unieważnij jeden.403 forbiddenscope_not_grantableTwoja rola nie może przyznać tych zakresów (details.scopes), np. webhooks:write jako editor.Co ponawiać
Ponów 429 po Retry-After sekundach, a 500 lub 503 z wykładniczym wycofaniem. Każde inne 4xx wymaga najpierw zmiany żądania. Żądania POST można bezpiecznie ponawiać, gdy wysyłasz ten sam Idempotency-Key.