Ga naar inhoud

Fouten en retries

Bedrijfsfouten retourneren code en message op het hoogste niveau van de responsbody. detail is meestal gelijk aan message, maar kan een andere, kortere uitleg zijn (zoals hieronder); toon message aan gebruikers. Berichten zijn in het Chinees:

{
"code": "CONCURRENCY_LIMITED",
"message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交",
"detail": "排队文件完成一部分后可继续提交"
}

Enkele bedrijfsfouten retourneren alleen code. Validatiefouten retourneren 422 met een lijst van veldfouten in detail:

{
"detail": [
{ "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
]
}

Behandel fouten eerst op basis van de HTTP-status en vervolgens op basis van code: veel fouten retourneren alleen de generieke UNKNOWN_ERROR, en slechts enkele bevatten een specifieke code (zoals de 429 gevallen hieronder). Noteer de X-Request-Id-responsheader voor probleemoplossing.

StatusBetekenisAdvies
400Ongeldig verzoek, bijvoorbeeld omdat de gekozen instelling niet beschikbaar is.Los het verzoek op; voer geen nieuwe poging uit
401Referentie ontbreekt, is ongeldig, verlopen of ingetrokkenWijzig de inloggegevens
402Het saldo (na aftrek van schulden) overschrijdt de taakdrempel niet, of het is negatief; bij een API-sleutel kan het resterende budget van de sleutel te laag zijn.Vul het budget van de sleutel aan (of verhoog het), en dien vervolgens opnieuw in.
403De limieten van de sleutel staan deze bewerking niet toe (bijvoorbeeld is de vertaalinstelling niet toegestaan), het account is uitgeschakeld, of de bewerking moet worden uitgevoerd in een ingelogde browser (zoals het beheren van API-sleutels)Controleer de belangrijkste instellingen of gebruik de website
404De resource bestaat niet, is verwijderd of behoort toe aan een ander account (alle drie zien er hetzelfde uit)Controleer de ID
409De idempotentiesleutel werd gebruikt voor een ander verzoek, of de status van de resource staat de bewerking niet toe.Query de oorspronkelijke bewerking en beslis vervolgens
410De resource of het eindpunt is definitief verwijderd, bijvoorbeeld een niet meer gebruikte endpoint of een verwijderde taak die aan een idempotentieel sleutel is gekoppeld.Probeer niet opnieuw
413Het bestand of de aanvraagtekst overschrijdt de limietGebruik een kleiner bestand
415Niet-ondersteund bestandsformaatGebruik een ander formaat
422Validatie mislukt, of het bestand is leeg of bevat niets om te verwerken.Los de velden op; voer geen automatische herhaling uit
429Snelheid, wachtrijgrootte of budget beperktZie hieronder
5xxTijdelijke servicefoutExponentiële backoff met een maximumaantal pogingen
codeBetekenisWat te doen
RATE_LIMITEDTe veel verzoekenWacht op Retry-After en probeer het vervolgens opnieuw
CONCURRENCY_LIMITEDEr staan te veel bestandstranslatietaken in de wachtrijWacht op Retry-After, of op de voltooiing van enkele taken
AUTH_API_KEY_QUOTA_EXCEEDEDHet budget van de sleutel is opgebruiktProbeer niet opnieuw totdat het budget is verhoogd.

Een 429 zonder Retry-After dient te worden verwerkt met exponentiële backoff.

  • Query’s kunnen rechtstreeks opnieuw worden uitgevoerd.
  • Wanneer u een aanmaakverzoek opnieuw probeert, gebruik dan dezelfde Idempotency-Key en exact dezelfde body; gebruik voor elke nieuwe indiening een nieuw sleutel.
  • Vraag na een mislukte upload een nieuw uploadadres aan.
  • Stel connect-, read- en totale time-outs in voor elk verzoek, voeg willekeurige jitter toe aan herhalingen en beperk het aantal pogingen.
import random
import time
for attempt in range(5):
response = call_api()
if response.status_code not in {429, 500, 502, 503, 504}:
break
if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
break
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
time.sleep(delay + random.random())