Falhas tratadas com clareza.

HTTP	Significado	Ação
400	Solicitação malformada	Corrigir a estrutura.
401	Credencial ausente/inválida	Corrigir ou rotacionar no servidor.
402	Saldo ou orçamento insuficiente	Rever saldo/teto; não fazer retry cego.
403	Scope ou licença insuficiente	Rever direitos e permissões.
404	Recurso inexistente ou não acessível	Conferir ID; não inferir dados de outro cliente.
409	Conflito de estado/idempotência	Mesmo ID de tentativa com payload diferente não é nova operação.
410	Objeto/cursor indisponível ou expirado	Consultar mudanças ou obter novo snapshot.
422	Input, escopo ou evidência inválidos	Corrigir campos e condição de qualidade.
429	Limite de requisições	Respeitar Retry-After e reduzir concorrência.
503	Capacidade temporariamente indisponível	Backoff com jitter e mesma chave idempotente.

Idempotência

Use uma chave estável por intenção de processamento. Reenvio com a mesma chave e o mesmo input retorna a operação original; input diferente com a mesma chave resulta em conflito. Retenção mínima proposta da chave: 48 horas. Não repetir após a janela sem reconciliar job e recibo.

Paginação e limites

Use cursor opaco, sem decodificar ou fabricar valores. Os limites exatos de cada endpoint estão na referência; quotas de organização e concorrência serão acordadas no onboarding. Tamanho de arquivo não equivale a páginas faturadas. Não há SLA operacional publicado nesta fase.

Diagnóstico seguro

Guarde request_id dos erros, correlationid dos eventos e identificadores do job/recibo. Não registre chaves, documentos privados nem nomes de alunos desnecessariamente. Envie identificadores de diagnóstico ao suporte, nunca segredos.