Anthropic 529 overloaded_error: cosa significa e come gestirlo

L'API Claude restituisce 529 con il tipo di overloaded_error errore quando l'API viene temporaneamente sovraccaricata. Secondo Anthropic, può verificarsi quando l'API registra un traffico elevato tra tutti gli utenti. La richiesta va bene. L'API è occupata, quindi ha rifiutato la richiesta. Quando l'organizzazione supera i propri limiti di frequenza, si riceve invece un errore 429. Il corpo della risposta ha la stessa forma di ogni altro errore dell'API Claude: un error di primo livello di error, un oggetto type con type e message, e un oggetto request_id che è possibile fornire al supporto Anthropic. Per altre informazioni, vedere Errori dell'API Claude.

529, 429 o limite di spesa: come distinguerli

L'API Claude usa errori dall'aspetto simile per problemi molto diversi. Alcuni problemi scompaiono se aspetti. Non se ne va fino al mese prossimo.

Un limite di spesa 429 ha lo stesso tipo di errore di un limite di frequenza, quindi il codice che ritenta ogni rate_limit_error continua a non riuscire. Anthropic nota che i tentativi falliscono fino a quando l'accesso non riprende, inclusi i tentativi automatici dell'SDK. Per maggiori dettagli, vedere Come raggiungere il limite di spesa.

Come gestire un 529

1. Controllare il codice di stato prima di riprovare. Un 529 e un 429 richiedono attese diverse, e un retry-after senza 429 non richiede alcun nuovo tentativo.
2. Interrompi in caso di errore 529. Riprovare con backoff esponenziale e jitter casuale e arrestarsi dopo alcuni tentativi. Se la risposta contiene un'intestazione retry-after, attendere invece per tale durata.
3. Consenti all’SDK di eseguire i primi tentativi di ripetizione. Gli SDK di Anthropic ufficiali ritentano in caso di errori di connessione, limiti di frequenza ed errori 5xx due volte per impostazione predefinita, con backoff esponenziale, e rispettano retry-after quando è presente. È possibile modificare il conteggio con max_retries (maxRetries in TypeScript). Quando l'SDK esaurisce i tentativi, il codice riceve l'errore.
4. Smettere di riprovare al raggiungimento di un limite di spesa. Se una risposta 429 non ha l'header retry-after, informare l'utente e avvisare se stessi.
5. Tenere informato l'utente. Accoda il lavoro e riprova più tardi, oppure visualizza un chiaro messaggio "occupato, riprova tra un minuto" anziché un errore generico.

Nell'SDK di Python, 429 genera anthropic.RateLimitError e qualsiasi stato 500 o superiore, incluso 529, genera anthropic.InternalServerError:

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

Come testare che l'app gestisca un 529

Ci si imbatte raramente in un 529 durante lo sviluppo. Dipende dal traffico di ogni utente dell'API Claude, quindi non puoi attivarlo. Il modo in cui si testa decide se trovi i bug prima che siano i tuoi utenti a trovarli.

Provalo nella tua app

Dev Proxy intercetta le richieste dell'app a https://api.anthropic.com e restituisce errori nel formato di errore di Anthropic, mentre l'app continua a chiamare l'URL reale. Scaricare un set di impostazioni e avviare Dev Proxy con esso:

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"

Nessun set di impostazioni include un limite di spesa 429. Per testare tale percorso, aggiungere una risposta senza intestazione retry-after al file anthropic-errors.json del preset:

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

Per fare in modo che ogni richiesta non riesca, in modo da vedere cosa accade quando l'SDK esaurisce i tentativi, avviare Dev Proxy con --failure-rate 100. Per altre informazioni, vedere Tasso di errore delle richieste di modifica. Per installare Dev Proxy, vedere Configurare Dev Proxy.

Passaggi successivi

Vedere anche

• 429 Troppe richieste: cosa significa e come gestirlo
• Errori 500, 502, 503 e 504 dalle API: cosa significano e come gestirli
• Che cos'è la limitazione?
• Verificare che l'applicazione gestisca correttamente la limitazione