Przejdź do dokumentacji

SYNDERESIS / API EKSPLOATACJA

Hostowane API dla klientów · Kontrakt przejrzany 7 listopada 2026

Integracja produkcyjna

Na tej stronie

Buduj wokół jawnych budżetów czasu, kosztów i niepowodzeń. Przykłady są punktem wyjścia; Twoja aplikacja odpowiada za uwierzytelnianie użytkowników końcowych, współbieżność, działania zewnętrzne i własne zobowiązania usługowe.

Błędy i środki zaradcze

Błędy natywnego API mają tę postać:

{
  "error": {
    "type": "unauthorized",
    "code": "unauthorized",
    "message": "Missing API key.",
    "request_id": "example-request-id"
  }
}

Przykładowy komunikat jest skrócony. type i code używają tego samego kodu maszynowego; message podaje wskazówki dla człowieka. Rozgałęziaj na podstawie pól status i code, zamiast dopasowywać tekst pola message. Zachowaj request_id na potrzeby wsparcia. Do przywrócenia działania nie powinno być potrzeby wewnętrznych dostawców ani śladów stosu.

HTTP i kod Znaczenie Działanie
400 invalid_request Nieprawidłowy JSON/obiekt, brakujące/błędne pola, nieprawidłowy transkrypt lub treść żądania ponad limitem punktu końcowego. Popraw żądanie. Limit Answers: 65536 bajtów; 921600 bajtów dla chat completions.
400 unsupported_model Alias nie jest akceptowany na tej ścieżce, na przykład labora z tools. Użyj wykrywania modeli i tabeli dispatch. synderesis-pro jest akceptowany jako ten sam wybór co pro.
400 unsupported_parameter W chat completions automatyczny wybór został połączony z tools lub wynikami narzędzi, albo na ścieżce odpowiedzi wysłano stream=true. Wybierz jawny model dla ścieżki narzędzi lub usuń stream. POST /v1/answers ignoruje stream i tools.
401 unauthorized Brakujące, nieprawidłowe, wygasłe/unieważnione lub sprzeczne poświadczenia. Popraw konfigurację poświadczeń.
402 free_allocation_exhausted Jednorazowy początkowy przydział tokenów został wyczerpany. Subskrybuj przez Konto lub potwierdź właściwe uprawnienie.
402 insufficient_credit Rozliczana praca na ścieżce odpowiedzi nie może zarezerwować wystarczających środków na koncie. Dodaj środki przez Konto i sprawdź swoje uprawnienie/taryfę.
402 inference_quota_exhausted Współdzielony klucz wyłącznie do inferencji nie może dopuścić żądania w ramach swojego limitu na cały okres istnienia. Przestań używać tego klucza; nie jest on uzupełniany.
403 inference_scope_denied Współdzielony klucz wyłącznie do inferencji wywołał trasę poza swoim zakresem. Używaj go tylko do odpowiedzi, chat completions i wykrywania modeli.
403 origin_invalid / csrf_invalid Kontrola pochodzenia sesji przeglądarki/CSRF nie powiodła się. Użyj obsługiwanego przepływu przeglądarki. Wywołania kluczem serwerowym nie powinny przenosić sesji przeglądarki.
404 not_found Nieznana ścieżka lub niedostępny przywoływany zasób. Sprawdź dokładny URL i bazę API.
405 method_not_allowed Ścieżka nie obsługuje tej metody. Użyj udokumentowanej metody; sprawdź Allow. Żądania OPTIONS przeglądarki nie są obsługiwane.
429 quota_exceeded Osiągnięto limit konta/planu. Sprawdź przydział/plan/resetowanie; powtarzane natychmiastowe próby tego nie rozwiążą.
429 rate_limited Ogranicznik specyficzny dla trasy odrzucił żądanie. Poczekaj, a następnie spróbuj ponownie w ramach ograniczonej polityki.
503 service_unavailable Nie udało się ukończyć zależności, podścieżki limitu albo operacji generowania. Sprawdź health, zastosuj ostrożne, ograniczone odzyskiwanie i zachowaj ID żądania.
500 internal_error Nieprzechwycony błąd granicy natywnej. Zachowaj ID żądania; traktuj wynik jako niepewny i skontaktuj się ze wsparciem, jeśli problem się utrzymuje.

Niektóre błędy inicjalizacji środowiska uruchomieniowego i granic mogą wystąpić przed normalną obsługą żądania. Nieoczekiwana odpowiedź może nie być JSON z powodu infrastruktury poza aplikacją; obsłuż ją bez ujawniania jej treści użytkownikom końcowym.

Ponowienia i niepewne wyniki

Nie ponawiaj automatycznie odpowiedzi walidacji, uwierzytelniania, nieobsługiwanego modelu ani wyczerpanej alokacji. Błędy limitu wymagają środka zaradczego w postaci planu albo resetu.

W przypadku żądania modelu lub wyszukiwania tylko do odczytu, gdy aplikacja akceptuje możliwe zdublowanie obliczeń i pomiaru zużycia, użyj niewielkiego budżetu ponowień dla błędów przejściowych. Jedną rozsądną polityką klienta jest próba początkowa plus co najwyżej dwa ponowienia, wykładnicze opóźnienie od 0.5 sekundy, losowy jitter i ogólny termin. To jest wskazówka dla aplikacji, a nie domyślne ustawienie SDK ani serwera Synderesis.

Uwzględniaj Retry-After, gdy jest obecny, ale nie polegaj na nim. Zatrzymaj się, jeśli błąd wskazuje na wyczerpaną pojemność, trwale nieprawidłowe żądanie albo nieznane działanie o rzeczywistych skutkach.

Idempotency-Key służy jako tożsamość rozliczenia lub rezerwacji na ścieżkach generowania. Nie jest udokumentowaną gwarancją generowania dokładnie raz ani API odtwarzania odpowiedzi z pamięci podręcznej. Ponowne użycie może napotkać końcowy albo niezgodny stan rezerwacji. Nie wnioskuj z jego istnienia, że automatyczna regeneracja jest bezpieczna.

Przekroczenie limitu czasu albo reset połączenia nie dowodzi, że serwer nie wykonał żadnej pracy. Uzgodnij użycie oraz identyfikatory żądań i użyj osobnego trwałego rejestru działań, aby uniknąć powtarzania skutków zewnętrznych narzędzi. Przejrzyj i jawnie skonfiguruj zachowanie ponawiania każdego SDK innej firmy.

Limity czasu i współbieżność

Ustaw w kliencie oraz w reverse proxy limity czasu połączenia, odczytu i ogólny limit czasu. Moduł obsługi transkryptu i narzędzi dopuszcza dłuższą operację upstream niż moduł krótkiej odpowiedzi; buforowane SSE nie usuwa czasu oczekiwania na generowanie.

Zacznij od niskiej współbieżności i skromnych górnych limitów danych wyjściowych. Zwiększaj je dopiero po zaobserwowaniu opóźnienia, limitu oraz zachowania środków dla swojego konta. Przejrzany publiczny kontrakt nie ustanawia uniwersalnej współbieżności ani gwarantowanej wartości opóźnienia.

Przekazuj anulowanie klienta dla higieny zasobów, zachowując stan o niepewnym wyniku. Anulowanie nie gwarantuje anulowania upstream ani zwrotu.

Monitorowanie

Zbieraj:

  • ID żądania oraz własny identyfikator korelacji aplikacji.
  • Endpoint i publiczny alias modelu.
  • Kod statusu lub błędu, opóźnienie i numer próby.
  • Zwrócone zużycie tokenów oraz trendy środków i alokacji na poziomie konta.
  • Liczba tur pętli narzędzi oraz niezależnie śledzone wyniki działań.

Używaj alertów przy utrzymujących się błędach, nieoczekiwanym wzroście użycia oraz przy wyczerpaniu limitu lub środków. Unikaj rejestrowania promptów albo kluczy. GET /health podaje gotowość, a GET /v1/usage stan konta; żadne z nich nie jest pełnym produkcyjnym SLA.

Zweryfikuj przed uruchomieniem

Potwierdź dokładny alias modelu i ścieżkę obsługi, semantykę rozmowy, limity body i danych wyjściowych oraz wszelkie uprawnienia funkcji. Przetestuj parser przy udanych odpowiedziach, pustych listach źródeł, treści wywołań narzędzi mogącej mieć wartość null, zakończeniach z powodu długości, nieznanych polach opcjonalnych, JSON błędu i niekompletnych strumieniach.

Przetestuj wyczerpanie konta lub środków w odpowiednim kontrolowanym układzie. Uzgodnij ograniczoną próbkę rzeczywistego użycia konta z uzgodnioną taryfą. Ustal warunki przetwarzającego i przechowywania oraz drogę wsparcia.

Utrzymuj rollback aplikacji, który może wyłączyć wywołania albo przełączyć na osobno kwalifikowaną konfigurację, bez cichego porzucania kontekstu użytkownika i bez powtarzania działań o rzeczywistych skutkach.

Kontakt i rozwiązywanie problemów

Użyj hello@synderesis.eu wraz z czasem UTC, endpointem, statusem HTTP, publicznym aliasem modelu i ID żądania. W razie potrzeby dołącz zredagowane minimalne żądanie. Nigdy nie dołączaj prawdziwego klucza API, cookie, prywatnego tekstu źródłowego ani niezredagowanych danych użytkownika.

Przejrzana dokumentacja nie ustanawia publicznego adresu URL strony statusu, zobowiązania co do poziomu usługi, gwarantowanego czasu odpowiedzi wsparcia ani umowy o automatyczny failover.

Czytaj ten przewodnik jako Markdown