Platform

Fouten

Fouten worden teruggestuurd als JSON in het formaat van het endpoint dat je hebt aangeroepen, met een leesbare melding en, bij endpoints in OpenAI-formaat, een vaste code voor programma's.

Het formaat

Endpoints in OpenAI-formaat

{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

Bij /v1/messages worden dezelfde fouten teruggestuurd in het formaat van Anthropic, dat geen code bevat: gebruik de HTTP-status en error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Elk antwoord op een chat-, afbeeldings- of videoverzoek, met of zonder fout, bevat een x-request-id-header.

Codes

Status	Code	Wat je kunt doen
400	`invalid_request`	Pas het verzoek aan: de melding geeft aan wat er mis is en param waar.
400	`unsupported_content`	Het model kan dit soort bestand niet lezen. Verwijder het of kies een model dat dat wel kan.
400	`invalid_url`	Een link in het verzoek kon niet worden gedownload. De melding bevat de ontvangen status.
400	`invalid_image`	Een invoerafbeelding kon niet worden gebruikt (type, grootte of link).
400	`image_not_generated`	Het model heeft de prompt geweigerd. Niet in rekening gebracht.
400	`context_length_exceeded`	Het model geeft aan dat het gesprek te lang is. Kort het in of kies een model met een langere context.
400	`max_tokens_reached`	Een antwoord via /v1/messages zonder streaming bereikte je max_tokens midden in een toolaanroep en is dus geen volledig bericht. Wat is gegenereerd, wordt in rekening gebracht. Verstuur het verzoek opnieuw met een hogere max_tokens.
401	`missing_api_key`	Stuur de sleutel mee in Authorization of x-api-key.
401	`invalid_api_key`	De sleutel is onjuist of ingetrokken.
401	`expired_api_key`	Maak een nieuwe sleutel aan.
402	`insufficient_quota`	Je saldo, min het bedrag dat je lopende verzoeken hebben gereserveerd, is niet genoeg voor dit verzoek, of raakte op tijdens een antwoord. Voeg tegoed toe onder Facturering of vraag om minder uitvoer met een lagere max_tokens. Als automatisch opwaarderen is gestart, staat dat in de melding: probeer het een paar seconden later opnieuw.
402	`key_budget_exceeded`	Het verzoek kan het maandbudget van de sleutel overschrijden, inclusief de lopende verzoeken, of heeft het budget onderweg bereikt. Verhoog het budget of wacht tot volgende maand.
402	`key_daily_budget_exceeded`	Hetzelfde geldt voor het dagbudget van de sleutel. Verhoog het of wacht tot middernacht UTC.
403	`model_not_allowed`	De sleutel mag dit model niet gebruiken.
403	`ip_not_allowed`	De sleutel werkt alleen vanaf andere adressen.
404	`model_not_found`	Controleer de model-ID op de modellenpagina.
404	`unknown_url`	Dit endpoint bestaat niet. Controleer het pad en de basis-URL.
404	`video_not_found`	Geen video met die ID in deze werkruimte.
404	`image_not_found`	Geen afbeeldingsverzoek met die ID in deze werkruimte (GET /v1/images/{id}, voor verzoeken met een callback_url).
409	`video_not_ready`	De video is nog niet klaar: blijf de status opvragen totdat deze completed is.
409	`video_failed`	De video is mislukt, dus er is niets om te downloaden. De foutmelding geeft aan waarom.
410	`video_expired`	De video is verwijderd, via de Bibliotheek of na 30 dagen.
413	`too_large`	Het verzoek of een bestand overschrijdt de limiet. Stuur grote bestanden als links.
429	`rate_limit_exceeded`	Wacht het aantal seconden uit retry-after en probeer het opnieuw.
429	`concurrency_limit_exceeded`	Er lopen al 32 verzoeken tegelijk in de werkruimte. Probeer het opnieuw na het aantal seconden uit retry-after, zodra er een is afgerond.
500	`server_error`	Er is aan onze kant iets misgegaan. Probeer het opnieuw.
502	`stream_interrupted`	Verstuurd als laatste event van een afgebroken stream. Wat vóór de onderbreking is gestreamd, wordt in rekening gebracht, daarna niets; probeer het opnieuw.
503	`model_unavailable`	Het model is momenteel niet beschikbaar. Probeer het opnieuw na het aantal seconden uit retry-after of schakel slimme routering in. Zonder retry-after en met x-should-retry: false is het model wel beschikbaar, maar geeft het bij dit verzoek telkens een foutmelding: verstuur het niet ongewijzigd opnieuw.
503	`server_restarting`	Zurelay herstart de machine die je verzoek verwerkte. Probeer het meteen opnieuw: een andere machine neemt het over. Niet in rekening gebracht, tenzij er al een stream was gestart: dan wordt wat je hebt ontvangen in rekening gebracht, net als bij een afgebroken stream.
503	`storage_unavailable`	Er is een afbeelding gemaakt, maar die kon niet worden afgeleverd. Niet in rekening gebracht; probeer het opnieuw.
503	`service_unavailable`	Een kortstondig probleem aan onze kant. Probeer het opnieuw.

Opnieuw proberen

Probeer 429 en 503 opnieuw na het aantal seconden in de retry-after-header (of met exponentieel oplopende wachttijden), tenzij het antwoord x-should-retry: false aangeeft.
Probeer andere 4xx-fouten niet ongewijzigd opnieuw: ze mislukken op dezelfde manier.
Mislukte verzoeken zijn gratis, dus opnieuw proberen kost niets totdat een verzoek slaagt. Een stream die onderweg afbreekt, wordt in rekening gebracht voor wat is afgeleverd, en de zeldzame 503 met x-should-retry: false voor de invoer (zie Facturering).
De officiële SDK's van OpenAI en Anthropic proberen bij de juiste fouten al automatisch opnieuw.

Fouten tijdens het streamen

Fouten die een model teruggeeft over je verzoek zelf (een parameter die het niet ondersteunt, een prompt die te lang is), worden doorgegeven met de eigen melding en code van het model, als een 400 van 422.

Fouten tijdens het streamen

Zodra een stream is gestart, kan een fout niet meer als HTTP-status worden doorgegeven. Je krijgt in plaats daarvan een laatste foutevent (in het formaat van het endpoint) en de stream stopt. De invoer en de uitvoer die je daarvoor hebt ontvangen, worden in rekening gebracht, daarna niets. Dit komt zelden voor: de meeste problemen worden vóór het eerste token opgevangen, waarna het verzoek opnieuw wordt geprobeerd.

Hetzelfde soort event beëindigt een stream als het saldo of het sleutelbudget onderweg opraakt, met insufficient_quota, key_budget_exceeded of key_daily_budget_exceeded. Een verzoek zonder streaming waarbij het saldo of budget onderweg opraakt, geeft terug wat er is geschreven, afgekapt zoals een antwoord dat max_tokens heeft bereikt (finish_reason: "length", of stop_reason: "max_tokens" bij /v1/messages), met een x-zurelay-stopped-header die de code vermeldt.

Vragen, of ontbreekt er iets? Vraag het ons supportteam en je krijgt antwoord per e-mail, meestal binnen een minuut.