Przejdź do głównej treści

Przegląd

API APIXO używa dwóch typów kodów błędów:
  1. Kody statusu HTTP — Zwracane natychmiast przy niepowodzeniu żądania
  2. Kody błędów zadania — Zwracane przy zapytaniu statusu, gdy przetwarzanie zadania się nie powiedzie
┌─────────────────────────────────────────────────────────────┐
│                      API Request Flow                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  POST /generateTask/{model}                                 │
│         │                                                   │
│         ├── Fail ──→ HTTP Status Code (400/401/429...)      │
│         │           Request rejected immediately             │
│         │                                                   │
│         └── Success ──→ 200 + taskId                        │
│                        Request accepted, task processing    │
│                             │                               │
│                             ▼                               │
│  GET /statusTask/{model}?taskId=xxx                         │
│         │                                                   │
│         ├── state: success ──→ resultUrls                   │
│         │                                                   │
│         └── state: failed ──→ Task Failure Code             │
│                               (failCode/failMsg)             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
TypKiedy wyzwalaneZnaczeniePrzykład
Kod statusu HTTPNatychmiast przy żądaniuSamo żądanie ma problemy401 Nieprawidłowy klucz API
Kod błędu zadaniaPrzy sprawdzaniu statusuZadanie zaakceptowane, ale przetwarzanie nie powiodło sięSensitiveContentDetected

Kody statusu HTTP

KodNazwaOpisDziałanie
200OKŻądanie pomyślnePrzetwórz odpowiedź normalnie
400Bad RequestNieprawidłowe parametry żądaniaSprawdź treść żądania
401UnauthorizedNieprawidłowy lub brakujący klucz APISprawdź klucz API
402Payment RequiredNiewystarczające saldoDoładuj konto
403ForbiddenTreść narusza politykęZmodyfikuj treść
404Not FoundZasób nie znalezionySprawdź ID modelu lub zadania
429Too Many RequestsPrzekroczony limit ratePoczekaj i spróbuj ponownie
500Server ErrorWewnętrzny błąd serweraSpróbuj później
503Service UnavailableSerwis tymczasowo niedostępnySpróbuj później

Kody błędów zadania

Gdy zadanie się nie powiedzie, odpowiedź zawiera failCode i failMsg:
{
  "code": 200,
  "message": "success",
  "data": {
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies."
  }
}

Naruszenia polityki treści

failCodeOpisRozwiązanie
SensitiveContentTreść narusza politykęZmodyfikuj prompt, unikaj wrażliwej treści
SensitiveContentDetectedTreść oznaczona jako naruszenieDostosuj treść promptu
InputImageSensitiveContentDetectedObraz wejściowy zawiera naruszenieUżyj zgodnego obrazu
InputOutputSensitiveContentDetectedWejście lub wyjście zawiera wrażliwą treśćSpróbuj ponownie z innym wejściem
NSFWWykryto treść NSFWUżyj zgodnego z polityką wejścia
ProhibitedContentDetectedWykryto niedozwoloną treśćSpróbuj z innym wejściem

Błędy promptu

failCodeOpisRozwiązanie
PromptLengthExceededPrompt przekracza limitSkróć prompt
PromptInvalidNieprawidłowy lub odrzucony promptSprawdź format i treść promptu

Błędy obrazu/mediów

failCodeOpisRozwiązanie
ImageFormatIncorrectNieprawidłowy format obrazuUżyj JPEG, PNG lub WebP
InvalidImageSizeNieprawidłowe wymiary obrazuSprawdź wymagania rozmiaru
Upload errorObraz przekracza limit 10MBSkompresuj obraz poniżej 10MB
INVALID_IMAGE_URLBrak dostępu do URL obrazuSprawdź dostępność URL
INVALID_LORA_URLNie można pobrać modelu LoRASprawdź URL LoRA

Limitowanie i kwoty

failCodeOpisRozwiązanie
RateLimitedLimit rate, spróbuj późniejZmniejsz częstotliwość żądań, poczekaj i spróbuj
RateLimitExceededPrzekroczony limit rateSpróbuj później
InsufficientQuotaNiewystarczająca kwotaSprawdź saldo konta

Błędy przetwarzania i systemu

failCodeOpisRozwiązanie
TimeoutLimit czasu odpowiedziSpróbuj później
Task TimeOutZadanie wygasło, generowanie nie powiodło sięPrzejdź do innego zadania
BadRequestBrak wymaganych parametrówSprawdź parametry żądania
MissingParameterBrak wymaganego parametruZobacz dokumentację API, dodaj parametr

Przykłady odpowiedzi błędów

Błąd HTTP (natychmiastowy zwrot)

400 - Błąd parametru
{
  "code": 400,
  "message": "Prompt exceeds provider limit (max 2000 chars)",
  "data": null
}
401 - Uwierzytelnienie nie powiodło się
{
  "code": 401,
  "message": "Invalid or missing API key",
  "data": null
}
429 - Limit rate
{
  "code": 429,
  "message": "Provider rate limited, please retry later",
  "data": null
}
504 - Timeout
{
  "code": 504,
  "message": "Provider timeout, please retry later",
  "data": null
}

Niepowodzenie zadania (przy sprawdzaniu statusu)

Naruszenie treści
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}
Treść NSFW
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "NSFW",
    "failMsg": "NSFW, Try different input please.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}
Błąd formatu obrazu
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "ImageFormatIncorrect",
    "failMsg": "Image format is incorrect",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}

Najlepsze praktyki obsługi błędów

Tylko 429, 500 i 504 są kandydatami do automatycznego ponowienia. Wszystkie inne błędy wymagają najpierw naprawy żądania.

1. Strategia ponowień

Typ błęduPonowić?Strategia
400 (Błąd parametru)NieNapraw parametry, potem spróbuj
401 (Błąd auth)NieSprawdź klucz API
429 (Limit rate)TakExponential backoff, poczekaj 60s i spróbuj
500 (Błąd serwera)TakExponential backoff, maks. 3 razy
504 (Timeout)TakPoczekaj i spróbuj, maks. 3 razy
Naruszenie treściNieZmodyfikuj treść, potem spróbuj
Błąd obrazuNieNapraw obraz, potem spróbuj

2. Przykład exponential backoff

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 429 || error.code >= 500) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

3. Wskazówki moderacji treści

Moderacja treści jest obsługiwana przez dostawców AI. Naruszeń nie można odwoływać przez APIXO — zmodyfikuj treść i prześlij ponownie.
Aby uniknąć błędów naruszenia treści:
  • Unikaj przemocy, pornografii, treści politycznie wrażliwych
  • Sprawdź, czy obrazy wejściowe są zgodne z polityką treści
  • Używaj jasnych, konkretnych opisów, unikaj niejednoznacznych sformułowań
  • Testuj najpierw prostą, bezpieczną treścią

4. Monitorowanie i logowanie

Zalecane logowanie do debugowania:
  • taskId — Unikalny identyfikator zadania
  • failCode — Kod błędu
  • failMsg — Komunikat błędu
  • Parametry żądania (zsanityzowane)

Błędy specyficzne dla dostawców

OpenAI

failCodeOpis
SensitiveContentDetectedTreść oznaczona przez OpenAI jako naruszenie
InputImageSensitiveContentDetectedObrazy zawierające prawdziwe osoby nie są obsługiwane

MidJourney

failCodeOpis
Website TimeOutWitryna MidJourney nie odpowiada po wielu próbach
INVALID_TASK_IDNieprawidłowe poprzednie ID zadania dla upscale/vary

Seedream (ByteDance)

failCodeOpis
outputimagesensitivecontentdetectedObraz wyjściowy zawiera wrażliwą treść
InvalidImageSizeNieprawidłowe wymiary obrazu

FAQ

P: Dostałem błąd 429, jak długo czekać?
O: Poczekaj 60 sekund, potem spróbuj ponownie, lub użyj strategii exponential backoff.
P: Jak uniknąć błędu PromptLengthExceeded?
O: Każdy model ma różne limity długości promptu, sprawdź dokumentację modelu. Ogólnie trzymaj się poniżej 2000 znaków.
P: Czy mogę odwołać błąd SensitiveContentDetected?
O: To wynik moderacji treści dostawcy AI. Zalecana modyfikacja treści i ponowne przesłanie.
P: Co zrobić z błędami 5xx?
O: To przejściowe problemy serwera. Użyj exponential backoff, maks. 3 razy. Jeśli się utrzymują, skontaktuj się z supportem.
Dlaczego status zadania zwraca 200, ale state to failed? HTTP 200 oznacza, że samo żądanie API powiodło się, ale zadanie generowania nie. Rzeczywisty błąd jest w failCode i failMsg, a nie w kodzie statusu HTTP.
P: Dlaczego status zadania zwraca 200, ale state to failed? O: HTTP 200 oznacza, że samo żądanie API powiodło się, ale wykonanie zadania nie (np. naruszenie treści). Rzeczywiste informacje o błędzie są w failCode i failMsg.

Wsparcie

Masz uporczywe błędy? Skontaktuj się z supportem, podając:
  • taskId — ID nieudanego zadania
  • failCode — Kod błędu
  • Parametry żądania (zsanityzowane)
  • Czas wystąpienia błędu
Wsparcie techniczne: support@apixo.ai