Dokumentacja

API v2 – katalog błędów

Pełny wykaz zadeklarowanych kodów błędów API v2, statusów HTTP i wyzwalaczy w środowisku produkcyjnym.

Błędy API v2 wykorzystują ustrukturyzowany obiekt error:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Niektóre błędy walidacji zawierają również opcjonalne pole details z informacjami na poziomie poszczególnych pól:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body",
    "details": {
      "fieldErrors": {
        "message": ["Too small: expected string to have >=1 characters"]
      }
    }
  }
}

Każda odpowiedź v2 zawiera nagłówek x-request-id. Podaj tę wartość w kontakcie z pomocą techniczną. Programuj w oparciu o error.code; wiadomości i szczegóły walidacji zapewniają kontekst czytelny dla człowieka.

Katalog błędów

Tabela zawiera wszystkie 30 kodów zadeklarowanych przez API v2. Myślnik oznacza, że kod jest zarezerwowany i nie ma obecnie żadnego miejsca wywołania w środowisku produkcyjnym v2, więc nie zdefiniowano dla niego statusu HTTP ani wyzwalacza.

KodStatus HTTPKiedy występujeUwagi
VALIDATION_INVALID_BODY400Treść żądania, wartość ścieżki, wartość zapytania, limit, cursor, źródło konwersacji, typ źródła lub dane wejściowe przetwarzania źródła nie przechodzą walidacji.Pole details jest dołączane tylko wtedy, gdy dostarcza je dane miejsce wywołania.
VALIDATION_INVALID_JSON400Punkt końcowy czatu, ponawiania, wyniku narzędzia lub informacji zwrotnej otrzymuje treść, która nie jest prawidłowym JSON-em.Pozostałe punkty końcowe zarządzania traktują zniekształcony JSON jako nieprawidłową treść żądania.
AUTH_MISSING_API_KEY401Uwierzytelniony punkt końcowy nie otrzymuje nagłówka Authorization albo jego wartość nie zaczyna się od Bearer .Punkt końcowy sprawdzający stan usługi nie wymaga uwierzytelnienia.
AUTH_INVALID_API_KEY401Nie udało się zweryfikować klucza API typu Bearer.Użyj aktywnego klucza API obszaru roboczego.
AUTH_EXPIRED_API_KEY—Zarezerwowany; obecnie nie jest zwracany przez żadną trasę produkcyjną v2.Nie zdefiniowano statusu ani wyzwalacza.
SUBSCRIPTION_PLAN_REQUIRED403Klucz API jest prawidłowy, ale jego obszar roboczy nie ma funkcji planu apiAccess.Dostęp do API wymaga planu Hobby lub wyższego z aktywnymi rozliczeniami.
SUBSCRIPTION_API_RESTRICTED_PLAN403Wywołujący włącza automatyczne ponowne trenowanie bez dostępu w ramach planu albo przesyła adres URL wideo bez dostępu do transkrypcji wideo.Sam klucz API pozostaje prawidłowy.
AUTH_INSUFFICIENT_PERMISSIONS—Zarezerwowany; obecnie nie jest zwracany przez żadną trasę produkcyjną v2.Nie zdefiniowano statusu ani wyzwalacza.
AGENT_NOT_FOUND404Żądanie dotyczące konkretnego agenta wskazuje agenta, który nie istnieje lub nie należy do konta powiązanego z kluczem API.Błędy własności konta zwracają tę samą odpowiedź co brakujący agent.
RESOURCE_NOT_FOUND404Nie można znaleźć konwersacji API v2 wymaganej przez operację pobrania szczegółów, wiadomości, ponowienia próby lub informacji zwrotnej.Operacje modyfikujące oraz lista wiadomości dotyczą wyłącznie konwersacji API v2.
RESOURCE_DOCUMENT_NOT_FOUND404Usunięcie źródła wskazuje dokument, który nie istnieje dla danego agenta.Nieprawidłowe identyfikatory dokumentów niebędące UUID zamiast tego skutkują błędem VALIDATION_INVALID_BODY.
RESOURCE_MESSAGE_NOT_FOUND404Informacja zwrotna wskazuje nieprawidłowy identyfikator wiadomości lub wiadomość, która nie znajduje się w podanej konwersacji API v2.Identyfikatory wiadomości to dodatnie wartości liczbowe zserializowane w odpowiedziach jako ciągi znaków.
RESOURCE_MESSAGE_NOT_ASSISTANT422Informacja zwrotna dotyczy wiadomości, która nie jest wiadomością asystenta AI.Wiadomości użytkownika oraz zapisy narzędzi nie mogą otrzymać informacji zwrotnej.
RESOURCE_TOOL_CALL_NOT_FOUND404Punkt końcowy wyniku narzędzia nie może dopasować podanego toolCallId do żadnej oczekującej akcji po stronie klienta.Wywołanie jest nieznane, wygasło albo należy do innej rozmowy API v2.
QUOTA_CHATBOT_LIMIT403Utworzenie agenta przekroczyłoby limit agentów obszaru roboczego.Przed ponowną próbą usuń agenta lub przejdź na wyższy plan.
QUOTA_STORAGE_LIMIT403Przetwarzanie źródła tekstowego lub Q&A zgłasza limit pamięci masowej, nowy adres URL nie mieści się w dostępnej pamięci masowej, albo utworzenie zadania dla adresu URL zgłasza przekroczenie limitu.Ponowne trenowanie istniejącego adresu URL nie zużywa dodatkowej pamięci masowej na dokumenty.
CHAT_MODEL_NOT_ALLOWED403Aktualizacja ustawień AI wybiera model niedostępny w planie obszaru roboczego.Wybierz dozwolony model albo przejdź na wyższy plan.
CHAT_CREDITS_EXHAUSTED—Zarezerwowany; obecnie nie jest zwracany przez żadną trasę produkcyjną v2.Nie zdefiniowano statusu ani wyzwalacza.
CHAT_AGENT_CREDITS_EXHAUSTED—Zarezerwowany; obecnie nie jest zwracany przez żadną trasę produkcyjną v2.Nie zdefiniowano statusu ani wyzwalacza.
CHAT_CONVERSATION_MISMATCH404Żądanie czatu podaje poprawnie sformatowany conversationId (≤128 znaków), który nie odpowiada żadnej konwersacji API v2 danego agenta.conversationId dłuższy niż 128 znaków jest odrzucany wcześniej błędem 400 VALIDATION_INVALID_BODY, a nie tym kodem. Pominięcie conversationId rozpoczyna nową konwersację.
CHAT_RETRY_MESSAGE_NOT_FOUND404Ponowienie próby otrzymuje niedodatni lub nie-całkowity identyfikator wiadomości, albo wskazany cel nie jest wiadomością asystenta AI w konwersacji API v2.Zapisy narzędzi nie mogą być celem ponowienia próby.
CHAT_RETRY_NO_USER_MESSAGE400Cel ponowienia próby nie ma wcześniejszej wiadomości użytkownika do odtworzenia.Ponowienie próby generuje odpowiedź na nowo od tury użytkownika bezpośrednio poprzedzającej wybraną odpowiedź asystenta.
INSTAGRAM_NOT_CONNECTED404Żądanie kanału Instagram wskazuje agenta bez połączenia z Instagramem.GET /channels/instagram zwraca { "connected": false } zamiast tego kodu.
INSTAGRAM_RECONNECT_REQUIRED409Funkcja wysyłania wiadomości prywatnych w odpowiedzi na komentarze zostaje włączona bez uprawnienia do komentarzy albo startery konwersacji są publikowane dla połączenia, którego stan nie jest connected.Ponownie połącz konto w panelu w sekcji Publikowanie → Instagram.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409Automatyzacja comment_to_dm lub story_leads zostaje włączona, gdy inna aktywna instancja jest już skierowana na ten sam post lub tę samą relację.Wyłącz drugą instancję albo wybierz inny post lub relację. Wersje robocze nigdy nie są odrzucane.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409Ogólna automatyzacja comment_to_dm lub story_leads (postScope / storyScope "any") zostaje włączona, gdy istnieje już aktywna ogólna automatyzacja tego typu.Najpierw wyłącz istniejącą ogólną automatyzację albo wybierz konkretny post lub relację.
INSTAGRAM_SYNC_IN_PROGRESS409Żądanie PATCH dotyczące menu stałego lub starterów konwersacji nakłada się na synchronizację tego samego zasobu i agenta.Ponów próbę po zakończeniu aktywnej publikacji lub czyszczenia.
INSTAGRAM_SYNC_FAILED502Synchronizacja menu stałego lub starterów konwersacji nie powiodła się.details.code jest dozwolonym kodem błędu; details.http_status i details.meta_code są liczbami lub mają wartość null. Tekst komunikatu Meta nigdy nie jest zwracany, a zapisany aktywny stan nadal opisuje ostatni potwierdzony stan.
RATE_LIMIT_TOO_MANY_REQUESTS—Zarezerwowany; obecnie nie jest zwracany przez żadną trasę produkcyjną v2.Nie zdefiniowano ani czasu ponawiania prób, ani zachowania nagłówka Retry-After.
INTERNAL_SERVER_ERROR500Utworzenie zadania dla adresu URL nie powiodło się z przyczyn niezwiązanych z limitem, albo ponowienie próby bez przesyłania strumieniowego nie wygenerowało żadnej zapisanej wiadomości asystenta.Podając awarię do zgłoszenia, dołącz x-request-id.

Powiązane materiały