Fouten, limieten en herhalingen

Elke Felo API retourneert een JSON-foutbody met een stabiele foutcode en een request-ID. Lees eerst de HTTP-status, dan de code en dan het bericht.

Foutformaat

Productieresponsen gebruiken momenteel de HTTP-status als status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Sommige oudere endpointvoorbeelden gebruiken status: "error" en een andere codereeks. Baseer je logica op de HTTP-status en code, niet op de exacte formulering van message.

Veelvoorkomende codes

Endpointreferenties vermelden de codes die specifiek zijn voor dat endpoint. Begin met de fouten van de Chat API of met de referentie van het endpoint dat je aanroept.

Endpoints voor modelgeneratie

POST /api/v1/images/generations en POST /api/v1/videos/generations retourneren fouten op endpointniveau in het OpenAI-foutformaat in plaats van het bovenstaande formaat:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

De request-ID staat in de X-Request-Id-responsheader, niet in de body. Een geweigerd verzoek maakt geen taak aan. Zodra een taak bestaat, komen de meeste fouten binnen als een definitieve taakstatus in een 200-respons in plaats van als HTTP-fout: controleer status op failed of interrupted en lees daarna error.message. Zie Beeldgeneratie en Asynchrone taken.

Request-ID's

Felo-foutbody's bevatten request_id. Log deze samen met het endpoint, de HTTP-status, de foutcode, het model-ID en het taak-ID. Log nooit de volledige API-sleutel.

De Model API accepteert ook een optionele X-Request-Id-verzoekheader. Als je er een meestuurt, wordt die voor diagnostiek teruggekaatst, zodat je je eigen logs aan een verzoek kunt koppelen. Stuur je er geen mee, gebruik dan de geretourneerde request_id.

Rate limits

/v2/chat is het enige Felo-endpoint met gedocumenteerde, afgedwongen rate limits:

• Per API-sleutel, venster van 1 minuut.
• Per gebruiker, venster van 1 minuut.
• Per gebruiker, venster van 1 uur.

Gebruikers met een actief betaald Felo-abonnement, inclusief enterprise-abonnementen, zijn vrijgesteld en ontvangen geen X-RateLimit-*-headers. Als de abonnementsstatus niet kan worden geverifieerd, gelden de limieten nog steeds.

Andere /v2/**-endpoints hebben momenteel geen afgedwongen rate limits. Verzoeken aan de Model API kunnen nog steeds door de upstream-provider worden beperkt, wat tot uiting kan komen als een 429.

Hardcode geen numerieke limieten. Lees de headers van elke respons.

Beleid voor nieuwe pogingen

Aanbevolen lus:

1. Probeer alleen idempotente of veilig te herhalen verzoeken opnieuw.
2. Gebruik exponentiële backoff: begin rond 1 seconde, verdubbel de wachttijd en stop bij 30 seconden.
3. Voeg willekeurige jitter toe zodat clients niet synchroon opnieuw proberen.
4. Stop na een klein aantal pogingen en toon de fout.
5. Houd bij een 429 Retry-After aan in plaats van je eigen schema.

Debugvolgorde

1. Controleer of de sleutel aanwezig en niet ingetrokken is.
2. Roep GET /api/v1/models aan met dezelfde sleutel om de authenticatie te bevestigen.
3. Stuur het kleinste geldige verzoek naar het doel-endpoint.
4. Voeg streaming, tools of grote invoer één voor één toe.
5. Controleer bij asynchroon werk de taakstatus voordat je opnieuw indient.

Gerelateerd

• Authenticatie
• Kanalen en providerroutering
• Asynchrone taken
• Problemen oplossen