Erros e idempotência
Erros padrão, repetições, limites e prevenção de duplicidade.
Erros usam application/problem+json, status HTTP real e request_id.
Criações exigem Idempotency-Key de 8–128 caracteres. Apenas o HMAC da Key e a impressão da requisição são armazenados. Mesma Key/corpo retorna a tarefa original; mesma Key/corpo diferente retorna 409 idempotency_conflict; uma requisição ativa retorna 409 request_in_progress. Nunca gere nova Key em repetição automática.
Códigos comuns: 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 e service_unavailable.
Credenciais inválidas repetidas do mesmo IP também são limitadas; apenas uma impressão de IP com Pepper HMAC é armazenada.
Repita falhas de rede, 429 e 503 com backoff, mesmo corpo e mesma Key. Se o resultado do Provider não puder ser confirmado, a API rejeita reenvio às cegas.
Sempre respeite o header Retry-After antes de repetir.