Dokumentacja dla deweloperówPierwsze kroki
Błędy
Jedna struktura błędu, stałe kody, jasne zasady ponawiania.
Każda odpowiedź z kodem spoza 2xx ma tę samą strukturę. Opieraj logikę na error.code, nigdy na message.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Pole | Zawartość |
|---|---|
code | Stały kod w formacie snake_case |
message | Po angielsku, do logów |
request_id | Także w X-Request-Id. Podaj go pomocy technicznej |
details[] | Przy 400/422: path, code, message dla każdego problemu |
Kody
| Status | Kod | Znaczenie | Co zrobić | Ponawiać |
|---|---|---|---|---|
| 400 | invalid_json | Treść nie jest prawidłowym JSON-em lub pole ma niewłaściwy typ. | Popraw treść zapytania. | Nie |
| 401 | unauthorized | Brak klucza API, nieprawidłowy format klucza lub nieznany klucz. | Wyślij nagłówek Authorization: Bearer cd_live_…; sprawdź, czy klucz został skopiowany w całości. | Nie |
| 401 | key_revoked | Klucz został unieważniony. | Utwórz nowy klucz w konsoli deweloperskiej. | Nie |
| 401 | key_expired | Klucz utracił ważność. | Utwórz nowy klucz w konsoli deweloperskiej. | Nie |
| 402 | insufficient_credits | Dostępne kredyty nie pokrywają najtańszego możliwego przebiegu tego zadania. | Kup pakiet kredytów lub poczekaj na miesięczne kredyty; nic nie zostało pobrane. | Nie |
| 403 | ip_not_allowed | Adresu IP, z którego przyszło wywołanie, nie ma na liście dozwolonych adresów klucza. | Wywołaj API z dozwolonego adresu IP lub zmień listę dozwolonych adresów. | Nie |
| 403 | subscription_inactive | Organizacja nie ma aktywnej subskrypcji obejmującej API. | Odnów subskrypcję. | Nie |
| 403 | account_inactive | Organizacja jest zawieszona albo nie ma właściciela z aktywnym kontem. | Skontaktuj się z pomocą techniczną. | Nie |
| 403 | scope_missing | Klucz nie ma zakresu wymaganego przez ten endpoint. | Użyj klucza z odpowiednim zakresem (pack:write, jobs:read, account:read, resources:read, resources:write). | Nie |
| 403 | preset_read_only | Presetów nie można zmieniać ani usuwać. | Utwórz własny pojazd przez POST /v1/vehicles. | Nie |
| 403 | plan_limit_reached | Pakiet organizacji nie pozwala na więcej projektów ani pozycji ładunku. | Usuń niepotrzebne projekty lub przejdź na wyższy pakiet. | Nie |
| 404 | not_found | Żaden endpoint /v1 nie ma tej metody i ścieżki. | Porównaj metodę i ścieżkę z listą endpointów. | Nie |
| 404 | job_not_found | W Twojej organizacji nie ma zadania o tym ID. | Sprawdź ID. | Nie |
| 404 | vehicle_not_found | Nie ma pojazdu o tym ID wśród presetów ani pojazdów Twojej organizacji. | Sprawdź ID w GET /v1/vehicles. | Nie |
| 404 | template_not_found | W Twojej organizacji nie ma szablonu o tym ID. | Sprawdź ID w GET /v1/templates. | Nie |
| 404 | project_not_found | W Twojej organizacji nie ma projektu o tym ID. | Sprawdź ID w GET /v1/projects. | Nie |
| 409 | job_not_finished | Zadanie wciąż czeka w kolejce lub jest w toku. | Odpytuj GET /v1/jobs/{id}, aż status będzie miał wartość succeeded. | Tak |
| 409 | project_busy | Dla projektu właśnie trwa planowanie załadunku (w aplikacji lub w innym zadaniu). | Poczekaj na zakończenie tego przebiegu i spróbuj ponownie. | Tak |
| 409 | job_failed | Zadanie zakończyło się błędem; nie ma wyniku. | Sprawdź job.error; za błędy po naszej stronie nie pobieramy opłat (time_limit_exceeded jest rozliczane jak anulowane zadanie) — wyślij zadanie ponownie, jeśli przyczyna była przejściowa. | Nie |
| 409 | job_canceled | Zadanie zostało anulowane; nie ma wyniku. | W razie potrzeby wyślij je ponownie. | Nie |
| 409 | job_already_finished | Zadanie już się zakończyło i nie można go anulować. | Nic nie trzeba robić. | Nie |
| 400 | idempotency_key_invalid | Nagłówek Idempotency-Key jest dłuższy niż 128 zn. | Użyj krótszego klucza (UUID się sprawdzi). | Nie |
| 410 | result_expired | Okres przechowywania wyniku minął i wynik został usunięty. | Jeśli znów potrzebujesz planu, wyślij zadanie ponownie. | Nie |
| 413 | payload_too_large | Treść zapytania przekracza 10 MB. | Ogranicz liczbę pozycji lub je uprość. | Nie |
| 422 | validation_failed | Zapytanie to poprawny składniowo JSON, ale opisuje nieprawidłowe zadanie. details[] zawiera wszystkie problemy. | Popraw każde pole wskazane w details[].path; błędy walidacji są bezpłatne. | Nie |
| 429 | rate_limited | Za dużo zapytań w bieżącej minucie, godzinie lub dobie (na klucz lub na organizację) albo przekroczony limit nieudanych uwierzytelnień z Twojego adresu IP (60 na minutę). | Odczekaj tyle sekund, ile podaje Retry-After, a potem ponów z backoffem. | Tak |
| 429 | too_many_jobs | Organizacja ma już maksymalną liczbę zadań w kolejce i w toku. | Poczekaj na zakończenie trwających zadań i spróbuj ponownie. | Tak |
| 500 | internal_error | Wystąpił błąd po naszej stronie. | Ponów z backoffem; jeśli błąd się powtarza, podaj request_id. | Tak |
| 503 | api_disabled | API jest tymczasowo wyłączone (prace konserwacyjne) lub wyłączone dla organizacji. | Spróbuj ponownie później. | Tak |
Szczegóły walidacji
details[].code przy 422 validation_failed:
| Kod | Znaczenie |
|---|---|
required | Brak wymaganego pola |
invalid_value | Zły typ lub wartość spoza dozwolonych |
out_of_range | Wartość za mała, za duża lub za długa |
duplicate_id | To samo ID użyte dwa razy |
unknown_vehicle | Brak presetu lub Twojego pojazdu o tym vehicle_id |
unknown_template | Brak Twojego szablonu o tym template_id |
type_not_allowed | Typ pojazdu niewłączony dla Twojej organizacji |
unknown_group | Pozycja wskazuje grupę, której nie ma na liście |
does_not_fit | Pozycja nie mieści się w żadnym z podanych pojazdów |
too_many_items | Więcej sztuk, niż pozwala limit zadania |
too_many_vehicles | Więcej pojazdów, niż pozwala limit zadania |
unknown_field | Pole nieznane API |
Błędy zadań
Zadanie failed lub canceled podaje przyczynę w job.error.code:
| Kod | Znaczenie |
|---|---|
canceled | Anulowane przez DELETE /v1/jobs/{id}. Pobrano opłatę podstawową i za zużyte obliczenia. |
time_limit_exceeded | Budżet obliczeniowy wyczerpał się, zanim załadowano jakikolwiek pojazd. Rozliczane jak anulowane zadanie: opłata za zadanie, dopłata za duży ładunek i zużyte obliczenia, nigdy opłata za pojazd. |
engine_failed | Błąd algorytmu załadunku. Bez opłat. |
queue_timeout | Zadanie zbyt długo czekało na wolne zasoby obliczeniowe. Bez opłat. |
server_restarted | Usługa została zrestartowana, gdy zadanie czekało w kolejce lub było w toku. Bez opłat. |
Ponawianie
Ponawiaj 429, 500 i 503 z wykładniczym backoffem, respektując Retry-After. Wysyłaj ten sam Idempotency-Key (Idempotencja). Innych błędów 4xx nigdy nie ponawiaj bez zmian.