Skip to main content

​
Formato do envelope de erro

Todos os erros seguem o mesmo formato: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_subject",
    "message": "subject é obrigatório.",
    "param": "subject"
  }
}
CampoDescrição
typeCategoria do erro
codeCódigo específico — use para lógica programática
messageDescrição legível em português
paramCampo que causou o erro (quando aplicável)

​
Tabela de erros

HTTPtypecodeQuando ocorreO que fazer
400invalid_request_errormissing_subjectsubject.doc ou subject.type ausenteVerificar o body da requisição
400invalid_request_errorinvalid_documentCPF/CNPJ com quantidade de dígitos incorretaValidar antes de enviar
400invalid_request_errorinvalid_subject_typesubject.type não é pf nem pjVerificar o campo
400invalid_request_errorsubject_type_mismatchTemplate PJ, mas subject.type: "pf" (ou vice-versa)Verificar o tipo do template
400invalid_request_errormissing_template_idtemplate_id ausenteAdicionar ao body
400invalid_request_errortemplate_not_foundtemplate_id inativo, errado ou de outro tenantVerificar o ID no dashboard
400invalid_request_errorinvalid_jsonJSON malformado no bodyVerificar o body
400invalid_request_errorinvalid_metadatametadata não é objeto ou tem tipos inválidosGarantir valores string
400invalid_request_errorinvalid_cursorCursor de paginação corrompidoUsar cursor retornado pelo GET /runs
400invalid_request_errorrun_not_foundrun_id inexistente ou de outro tenantVerificar o ID
401authentication_errormissing_api_keyHeader x-api-key ausenteAdicionar o header
401authentication_errorinvalid_api_keyKey revogada, inativa ou incorretaVerificar a key no dashboard
402billing_errorbilling_suspendedSaldo insuficiente ou conta suspensaAdicionar créditos no dashboard
403authorization_errorinsufficient_scopeKey sem o escopo necessárioCriar key com o escopo correto
403authorization_errorsubject_type_not_allowedKey restrita a PF, mas enviou PJ (ou vice-versa)Verificar escopos da key
429server_errorrate_limit_exceededLimite de requisições atingidoAguardar Retry-After segundos
500server_errorinternal_errorFalha internaTentar novamente com backoff
500server_errorrun_not_createdFalha ao criar o run (erro interno)Tentar novamente com Idempotency-Key
500server_errorrun_failedFalha ao iniciar o runTentar novamente

​
Estratégia de retry para clientes da API

Para chamadas à API que falham com erros temporários, use backoff exponencial:
StatusReintentar?Estratégia
429 (rate limit)SimAguardar Retry-After header (em segundos)
500, 502, 503, 504SimBackoff: 1s, 2s, 4s, 8s, 16s (máx 5 tentativas)
400NãoErro de validação — corrigir o request
401, 403NãoErro de autenticação — verificar a API key
404NãoRecurso não encontrado — não tente novamente
Rate limit: 60 requisições por minuto por API key. Runs que excedem o limite retornam 429 com header Retry-After: 60. 
async function callWithRetry(fn: () => Promise<Response>, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fn()
    if (res.ok) return res
    if (res.status === 429) {
      const wait = parseInt(res.headers.get('Retry-After') ?? '60') * 1000
      await new Promise(r => setTimeout(r, wait))
      continue
    }
    if (res.status >= 500 && attempt < maxAttempts) {
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000))
      continue
    }
    throw new Error(`API error: ${res.status}`)
  }
}
Use Idempotency-Key em POST /runs para garantir que retries não criem runs duplicados. Veja Idempotência.