CometAPI 401-, 404-, 429- en 5xx-fouten: opnieuw proberen of afbreken?

Kort antwoord: schakel niet van Claude naar GPT bij elke mislukte request. Een 401 betekent dat de authenticatie moet worden hersteld, en een pad-gerelateerde 404 betekent dat de URL of endpoint moet worden gecorrigeerd. Een 429 of tijdelijke 5xx kan met backoff opnieuw worden geprobeerd; als begrensde retries nog steeds mislukken, kan een compatibel fallback-model overnemen.

Er is één belangrijke uitzondering: een 500-respons met error.code: invalid_request blijft een requestprobleem. Opnieuw proberen — of dezelfde kapotte payload naar een ander model sturen — maskeert alleen de bug.

Dit artikel is op 20 augustus 2026 geverifieerd aan de hand van CometAPI’s documentatie over errors, retries, basis-URL, rate limits en model-fallback. Het behandelt uitsluitend foutclassificatie. Voor routeontwerp, provider-credentials en meerlagige failover, gebruik de volledige model-fallback-tutorial en de technische fallback-gids.

Begin met de beslissing: opnieuw proberen of stoppen

De praktische vraag is niet “Heeft Claude gefaald?” maar “Zou een ander model kunnen slagen zonder het ongeldige deel van deze request te wijzigen?” Authenticatie- en padfouten raken de verbinding zelf, dus het wijzigen van het model kan ze niet oplossen. Tijdelijke capaciteits- en serverstoringen kunnen route-specifiek zijn, dus een fallback kan helpen.

Lees de fout voordat u van model wisselt

Gebruik de HTTP-status samen met error.code en error.message. Veel CometAPI-fouten gebruiken een envelop als deze:

{
  "error": {
    "message": "human-readable detail and request id",
    "type": "comet_api_error",
    "param": "problematic_parameter_or_empty",
    "code": "error_code_or_empty"
  }
}

Classificeer niet alleen op basis van het eerste cijfer van de statuscode. Een 500 kan nog steeds invalid_request bevatten, terwijl een verkeerd CometAPI-pad een redirect of HTML kan teruggeven in plaats van een nette JSON-404.

401 Unauthorized: stop en herstel de authenticatie

Een 401 betekent meestal dat de API-sleutel ontbreekt, onjuist is, verlopen is of uit de verkeerde omgeving is geladen. De header moet zijn:

Authorization: Bearer $COMETAPI_KEY

Probeer niet opnieuw en schakel niet van model. Beide routes gebruiken dezelfde ongeldige authenticatie. Controleer of de gedeployde service een oude secret heeft geladen, of er witruimte aan de sleutel is toegevoegd, en of de request de bedoelde omgeving bereikt. Roteer of herlaad de sleutel alleen via uw secretmanagement-proces.

404 Not Found: herstel de URL vóór fallback

Voor OpenAI-compatibele requests, gebruik exact deze basis-URL:

https://api.cometapi.com/v1

Een ontbrekende /v1, een dubbel padsegment of het verkeerde endpoint kan 404, een redirect, een HTML-respons of een SDK-parsefout opleveren. Schakel het automatisch volgen van redirects uit tijdens het debuggen en bevestig het definitieve requestpad aan de hand van de API-referentie.

Als de respons expliciet aangeeft dat een model niet beschikbaar is of niet is gevonden, verifieer dan de model-ID in de huidige CometAPI Models API. Behandel niet elke 404 als modelonbeschikbaarheid. Voeg pas een model-specifieke fallback toe nadat u precies dat signaal hebt vastgelegd en getest.

429 Too Many Requests: backoff vóór fallback

Een 429 is opnieuw te proberen. Gebruik exponentiële backoff met jitter, verlaag burst-concurrency, en meet welke route verzadigt. Een onmiddellijke retry door elke worker kan een korte rate limit veranderen in een grotere verkeerspiek.

Na een klein, begrensd aantal retries kan fallback passend zijn wanneer het volgende model dezelfde input, outputcontract en vereiste capaciteiten ondersteunt. Fallback is niet gratis: het voegt latentie toe en kan kosten of gedrag veranderen, dus registreer hoe vaak het wordt gebruikt.

5xx-fouten: controleer de code, dan opnieuw proberen

500, 503, 504 en 524 vertegenwoordigen vaak platform-, provider- of timeout-klasse storingen. Bewaar de request-ID, endpoint, model en tijdstempel en probeer vervolgens opnieuw met backoff. Als dezelfde tijdelijke storing de retry-begroting overleeft, ga dan door naar de volgende compatibele route.

Maar inspecteer eerst de body. Wanneer een 500 error.code: invalid_request of invalid_request_error bevat, corrigeer de requestbody en probeer pas opnieuw nadat deze is gewijzigd. Veelvoorkomende oorzaken zijn een ontbrekend messages-veld of een provider-specifieke parameter die het geselecteerde endpoint niet accepteert.

Gebruik één kleine beleidsregel in code

Dit Python-voorbeeld houdt retries en fallback in de applicatie. Het gebruikt één CometAPI-sleutel, de OpenAI-compatibele basis-URL en omgevingsvariabelen voor de huidige Claude- en GPT-model-ID’s. Het probeert alleen tijdelijke storingen opnieuw, en wisselt daarna van model wanneer de retry-begroting op is.

import os, random, time
from openai import APIError, OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
    max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}

def complete(messages):
    for model in MODELS:
        for attempt in range(3):
            try:
                response = client.chat.completions.create(model=model, messages=messages)
                return response.choices[0].message.content
            except APIError as error:
                status = getattr(error, "status_code", None)
                code = getattr(error, "code", None)
                if status in {401, 404} or code in {
                    "invalid_request", "invalid_request_error"
                }:
                    raise
                if status not in RETRYABLE:
                    raise
                if attempt < 2:
                    time.sleep(2**attempt + random.random())
                    continue
                break
    raise RuntimeError("No configured route completed.")

print(complete([{"role": "user", "content": "Summarize this ticket."}]))

De automatische retries van de SDK zijn uitgeschakeld zodat de applicatie eigenaar is van de totale retry- en fallback-begroting. Zonder die controle kunnen SDK-retries plus applicatie-retries de aanroepen vermenigvuldigen en de uiteindelijke respons vertragen.

Test het beleid zonder te raden

Dit zijn beleidstests, geen uitspraken over de betrouwbaarheid van live providers. Injecteer in staging de status en error-body in de classifier, verifieer het aantal en de volgorde van aanroepen, en bevestig dat uw uiteindelijke fout nog steeds de oorspronkelijke requestcontext bevat.

Wanneer Claude-naar-GPT-fallback daadwerkelijk veilig is

Wisselen tussen modelfamilies is alleen veilig wanneer beide routes aan hetzelfde applicatiecontract kunnen voldoen. Normaliseer de request- en responsevelden, test gestructureerde output of toolgedrag op beide modellen, en verifieer elke vereiste mogelijkheid voor afbeeldingen, documenten, context of redeneren voordat u de route inschakelt.

Fallback moet ook neveneffecten respecteren. Als de eerste route al een tool heeft geactiveerd, data heeft weggeschreven of een partial respons heeft gestreamd, kan het blind herhalen van de volledige request acties dupliceren of de gebruiker in verwarring brengen. Hervat vanaf een checkpoint of geef in plaats daarvan een gecontroleerde fout terug.

Productiecontroles die retries begrenzen

• Stel één totale latentie-budget vast. Tel elke retry en fallback mee tegen dezelfde deadline.
• Beperk retries. Gebruik backoff met jitter en stop na een kleine, geconfigureerde limiet.
• Beheer gelijktijdigheid. Verminder bursts voordat requests de applicatie verlaten.
• Voeg een circuit breaker toe. Stop tijdelijk met het aanroepen van een route die herhaaldelijk faalt.
• Log beslissingen. Leg status, errorcode, request-ID, model, poging, vertraging en fallback-reden vast zonder secrets op te slaan.
• Houd de fallbackfrequentie bij. Een aanhoudende stijging is een operationeel signaal, geen normale succesmetric.

Veelgestelde vragen

Moet een 401 ooit een modelfallback triggeren?

Nee. Herstel of herlaad de API-sleutel. Een ander model dat via dezelfde ongeldige credentials wordt aangeroepen, zal om dezelfde reden falen.

Moet een 404 fallback triggeren?

Niet standaard. Herstel eerst de basis-URL of het endpoint. Alleen een afzonderlijk geverifieerd signaal “model niet beschikbaar” mag de fallback-classifier binnenkomen.

Hoe vaak moet ik een 429 opnieuw proberen?

Gebruik een kleine, door de applicatie gedefinieerde limiet die past binnen het voor de gebruiker zichtbare latentie-budget. Pas backoff met jitter toe en verlaag gelijktijdigheid; probeer niet onmiddellijk en niet onbeperkt opnieuw.

Zijn alle 5xx-fouten opnieuw te proberen?

Nee. Tijdelijke 500, 503, 504 en 524-responses zijn kandidaten voor opnieuw proberen, maar 500 met invalid_request moet hard falen totdat de payload is gecorrigeerd.

Kunnen Claude en GPT dezelfde ongewijzigde request gebruiken?

Alleen voor de gedeelde velden die uw applicatie heeft getest. Provider-specifieke parameters, toolformaten, gestructureerde outputs en multimodale inputs kunnen adapters vereisen. Alleen een wijziging van de model-ID bewijst geen compatibiliteit.

Waar staat de volledige fallback-implementatie?

Zie How to Build Robust LLM Model Fallback Strategies voor de bredere architectuur, en de CometAPI model fallback guide voor implementatiedetails.

Maak van de foutclassifier de poortwachter

Automatische fallback is nuttig wanneer deze smal en observeerbaar is. Laat authenticatie-, pad- en malformed-request-fouten hard falen. Probeer rate limits en tijdelijke serverstoringen opnieuw met backoff, en schakel pas over naar een compatibele route nadat de retry-begroting is verbruikt. Dat beleid maakt van fallback een betrouwbaarheidsmaatregel in plaats van een manier om configuratiebugs te verbergen.

Bronnen

• CometAPI error codes and handling
• CometAPI error and retry strategy
• CometAPI rate limits and concurrency
• CometAPI base URL guide
• CometAPI model and provider fallback guide
• CometAPI complete model fallback tutorial