Errori e idempotenza
Errori standard, retry, limiti e prevenzione duplicati.
Gli errori usano application/problem+json, stato HTTP reale e request_id.
Le creazioni richiedono un Idempotency-Key di 8–128 caratteri. Vengono salvati solo HMAC e impronta della richiesta. Stessa Key/corpo restituisce l'attività originale; stessa Key/corpo diverso restituisce 409 idempotency_conflict; una richiesta attiva restituisce 409 request_in_progress. Non generare nuove Key nei retry automatici.
Codici comuni: invalid_api_key, invalid_api_key_rate_limited, api_key_expired, insufficient_scope, validation_error, unsupported_model, unsupported_parameter, input_url_not_allowed, insufficient_credits, payment_required, account_suspended, network_not_allowed, rate_limit_exceeded, concurrency_limit_exceeded, provider_unavailable, service_unavailable.
Anche credenziali errate ripetute dallo stesso IP vengono limitate; si salva solo un'impronta IP con Pepper HMAC.
Riprova errori di rete, 429 e 503 con backoff, stesso corpo e stessa Key. Se l'esito del Provider non è confermabile, l'API rifiuta il reinvio cieco.
Rispetta sempre l'header Retry-After prima di riprovare.