Przegląd
API APIXO używa dwóch typów kodów błędów:
- Kody statusu HTTP — Zwracane natychmiast przy niepowodzeniu żądania
- 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) │
│ │
└─────────────────────────────────────────────────────────────┘
| Typ | Kiedy wyzwalane | Znaczenie | Przykład |
|---|
| Kod statusu HTTP | Natychmiast przy żądaniu | Samo żądanie ma problemy | 401 Nieprawidłowy klucz API |
| Kod błędu zadania | Przy sprawdzaniu statusu | Zadanie zaakceptowane, ale przetwarzanie nie powiodło się | SensitiveContentDetected |
Kody statusu HTTP
| Kod | Nazwa | Opis | Działanie |
|---|
200 | OK | Żądanie pomyślne | Przetwórz odpowiedź normalnie |
400 | Bad Request | Nieprawidłowe parametry żądania | Sprawdź treść żądania |
401 | Unauthorized | Nieprawidłowy lub brakujący klucz API | Sprawdź klucz API |
402 | Payment Required | Niewystarczające saldo | Doładuj konto |
403 | Forbidden | Treść narusza politykę | Zmodyfikuj treść |
404 | Not Found | Zasób nie znaleziony | Sprawdź ID modelu lub zadania |
429 | Too Many Requests | Przekroczony limit rate | Poczekaj i spróbuj ponownie |
500 | Server Error | Wewnętrzny błąd serwera | Spróbuj później |
503 | Service Unavailable | Serwis tymczasowo niedostępny | Spró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
| failCode | Opis | Rozwiązanie |
|---|
SensitiveContent | Treść narusza politykę | Zmodyfikuj prompt, unikaj wrażliwej treści |
SensitiveContentDetected | Treść oznaczona jako naruszenie | Dostosuj treść promptu |
InputImageSensitiveContentDetected | Obraz wejściowy zawiera naruszenie | Użyj zgodnego obrazu |
InputOutputSensitiveContentDetected | Wejście lub wyjście zawiera wrażliwą treść | Spróbuj ponownie z innym wejściem |
NSFW | Wykryto treść NSFW | Użyj zgodnego z polityką wejścia |
ProhibitedContentDetected | Wykryto niedozwoloną treść | Spróbuj z innym wejściem |
Błędy promptu
| failCode | Opis | Rozwiązanie |
|---|
PromptLengthExceeded | Prompt przekracza limit | Skróć prompt |
PromptInvalid | Nieprawidłowy lub odrzucony prompt | Sprawdź format i treść promptu |
Błędy obrazu/mediów
| failCode | Opis | Rozwiązanie |
|---|
ImageFormatIncorrect | Nieprawidłowy format obrazu | Użyj JPEG, PNG lub WebP |
InvalidImageSize | Nieprawidłowe wymiary obrazu | Sprawdź wymagania rozmiaru |
Upload error | Obraz przekracza limit 10MB | Skompresuj obraz poniżej 10MB |
INVALID_IMAGE_URL | Brak dostępu do URL obrazu | Sprawdź dostępność URL |
INVALID_LORA_URL | Nie można pobrać modelu LoRA | Sprawdź URL LoRA |
Limitowanie i kwoty
| failCode | Opis | Rozwiązanie |
|---|
RateLimited | Limit rate, spróbuj później | Zmniejsz częstotliwość żądań, poczekaj i spróbuj |
RateLimitExceeded | Przekroczony limit rate | Spróbuj później |
InsufficientQuota | Niewystarczająca kwota | Sprawdź saldo konta |
Błędy przetwarzania i systemu
| failCode | Opis | Rozwiązanie |
|---|
Timeout | Limit czasu odpowiedzi | Spróbuj później |
Task TimeOut | Zadanie wygasło, generowanie nie powiodło się | Przejdź do innego zadania |
BadRequest | Brak wymaganych parametrów | Sprawdź parametry żądania |
MissingParameter | Brak wymaganego parametru | Zobacz 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łędu | Ponowić? | Strategia |
|---|
400 (Błąd parametru) | Nie | Napraw parametry, potem spróbuj |
401 (Błąd auth) | Nie | Sprawdź klucz API |
429 (Limit rate) | Tak | Exponential backoff, poczekaj 60s i spróbuj |
500 (Błąd serwera) | Tak | Exponential backoff, maks. 3 razy |
504 (Timeout) | Tak | Poczekaj i spróbuj, maks. 3 razy |
| Naruszenie treści | Nie | Zmodyfikuj treść, potem spróbuj |
| Błąd obrazu | Nie | Napraw 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
| failCode | Opis |
|---|
SensitiveContentDetected | Treść oznaczona przez OpenAI jako naruszenie |
InputImageSensitiveContentDetected | Obrazy zawierające prawdziwe osoby nie są obsługiwane |
MidJourney
| failCode | Opis |
|---|
Website TimeOut | Witryna MidJourney nie odpowiada po wielu próbach |
INVALID_TASK_ID | Nieprawidłowe poprzednie ID zadania dla upscale/vary |
Seedream (ByteDance)
| failCode | Opis |
|---|
outputimagesensitivecontentdetected | Obraz wyjściowy zawiera wrażliwą treść |
InvalidImageSize | Nieprawidł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