Błędy i limity

Format błędów, kody HTTP, nazwy błędów, limity zapytań i nagłówki RateLimit.

Na tej stronie

Gdy zapytanie się nie powiedzie, API zwraca kod HTTP i błąd w stałym formacie. Nazwa błędu w polu name jest stabilna, więc to na niej opieraj logikę, a nie na treści komunikatu.

Format błędu

Błąd

{
  "success": false,
  "error": {
    "message": "Opis zrozumiały dla człowieka",
    "name": "noPermissions",
    "extra": {}
  }
}

Pole	Znaczenie
`message`	Opis błędu. Może się zmieniać, nie porównuj go w kodzie
`name`	Stała nazwa błędu
`extra`	Szczegóły zależne od błędu, na przykład brakujące uprawnienia

Kody HTTP

Kod	Kiedy
`400`	Nieprawidłowe zapytanie albo wartość pola
`401`	Brak uwierzytelnienia, zły albo wygasły klucz lub token
`402`	Funkcja nie jest dostępna w planie albo workspace jest zawieszony
`403`	Brak uprawnień do zasobu albo operacji
`404`	Zasób nie istnieje albo identyfikator jest błędny
`429`	Przekroczony limit zapytań
`500`	Błąd po stronie Hypris. Spróbuj ponownie, a jeśli się powtarza, napisz do nas

Najczęstsze błędy

`name`	Kod	Co zrobić
`INVALID_REQUEST`	`400`	Popraw treść zapytania według `extra.validationErrors`
`INVALID_FIELD_VALUE`	`400`	Popraw kształt wartości pola, zobacz Wartości pól
`noPermissions`	`403`	Poproś o brakujące uprawnienia z `extra.missingPermissions`
`FORBIDDEN`	`403`	Ta operacja wymaga innego rodzaju dostępu
`not-found`	`404`	Sprawdź identyfikator i dostęp do zasobu
`TOO_MANY_REQUESTS`	`429`	Odczekaj czas z nagłówka `Retry-After`
`plan-feature-not-entitled`	`402`	Funkcja nie jest dostępna w planie workspace
`workspace-suspended`	`402`	Dostęp do workspace jest wstrzymany z powodu nieopłaconej subskrypcji

Błąd walidacji

Gdy treść, parametry albo adres nie pasują do schematu endpointu, dostajesz listę problemów:

400 Bad Request

{
  "success": false,
  "error": {
    "message": "Invalid request",
    "name": "INVALID_REQUEST",
    "extra": {
      "error": "…",
      "validationErrors": [
        {"path": ["cellValues"], "message": "Expected object, received string"}
      ]
    }
  }
}

Błędne wartości pól

Wartość w złym kształcie, na przykład data jako zwykły napis albo nazwa statusu zamiast identyfikatora, kończy się błędem INVALID_FIELD_VALUE. Komunikat mówi, które pole i dlaczego. Najpewniejszy sposób, żeby go uniknąć, to budowanie wartości z exampleCellValue, jak opisuje przewodnik Wartości pól.

Limity zapytań

Zakres	Limit
Wszystkie zapytania do API i MCP	600 na minutę z jednego adresu IP
Dynamiczna rejestracja klienta OAuth	10 na godzinę z jednego adresu IP
Nasłuch webhooka	Domyślnie 120 na minutę na nasłuch

Każda odpowiedź objęta limitem ma nagłówki:

Nagłówek	Znaczenie
`RateLimit-Limit`	Limit w bieżącym oknie
`RateLimit-Remaining`	Ile zapytań zostało
`RateLimit-Reset`	Za ile sekund okno się odnowi
`Retry-After`	Przy odpowiedzi `429`: ile sekund odczekać

Ponawianie zapytań

Ponawiaj tylko błędy 429 i 5xx. Przy 429 odczekaj tyle, ile mówi Retry-After. Przy 5xx wydłużaj przerwy wykładniczo:

JavaScript

async function fetchWithRetry(url, options, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const response = await fetch(url, options)
    if (response.status !== 429 && response.status < 500) {
      return response
    }
    const retryAfter = Number(response.headers.get('Retry-After'))
    const delay = retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 500
    await new Promise(resolve => setTimeout(resolve, delay))
  }
  throw new Error('Hypris API nie odpowiada')
}