Errores e idempotencia
Errores estándar, reintentos, límites y prevención de duplicados.
Los errores usan application/problem+json, el estado HTTP real y request_id.
Las creaciones requieren un Idempotency-Key de 8–128 caracteres. Solo se guarda su HMAC y la huella de la solicitud. Misma Key/cuerpo devuelve la tarea original; misma Key/cuerpo distinto devuelve 409 idempotency_conflict; una solicitud activa devuelve 409 request_in_progress. Nunca generes una Key nueva en un reintento automático.
Códigos habituales: 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 y service_unavailable.
Las credenciales inválidas repetidas desde una IP también se limitan; solo se almacena una huella de IP con Pepper HMAC.
Reintenta fallos de red, 429 y 503 con backoff, el mismo cuerpo y la misma Key. Si no puede confirmarse el resultado del Provider, la API rechaza el reenvío ciego.
Respeta siempre el header Retry-After antes de reintentar.