Códigos de erro

Referência dos erros públicos, status HTTP, possibilidade de repetição e ação corretiva recomendada.

Nesta página

Formato
Códigos
Repetição
X-Request-Id

Formato do erro

{
  "error": {
    "code": "invalid_distributor_credentials",
    "message": "The distributor rejected the username or password as incorrect. Authorize again with the correct password and try again.",
    "retryable": false,
    "details": {}
  }
}

Use code para lógica. Exiba ou registre message. Consulte details para contexto. retryable responde apenas se repetir mais tarde pode funcionar sem corrigir a requisição.

Todos os códigos públicos

Código	HTTP	Repetível	Ação
`invalid_api_key`	401	não	Confira a chave e o ambiente.
`client_account_inactive`	403	não	Peça a reativação da conta.
`client_scope_forbidden`	403	não	Use o próprio cliente da chave ou uma chave administrativa.
`api_key_ip_not_allowed`	403	não	Use a chave administrativa a partir do IP cadastrado.
`authentication_service_unavailable`	503	sim	Aguarde e tente novamente.
`client_lookup_unavailable`	503	sim	Aguarde e repita a consulta por nome, ou use clientId.
`invalid_request`	422	não	Corrija campos, tipos ou parâmetros informados em details.fields.
`invalid_job_status`	400	não	Use ANY, SUCCESS ou um estado de trabalho documentado.
`invalid_client_id`	400	não	Informe um clientId não vazio.
`invalid_client_name`	400	não	Informe um clientName não vazio.
`client_filter_mismatch`	400	não	Faça clientId e clientName identificarem o mesmo cliente.
`ambiguous_client_name`	409	não	Use clientId para distinguir clientes legados com o mesmo nome.
`invalid_distributor`	400	não	Use CELESC ou COPEL no filtro dist.
`conflicting_date_filters`	400	não	Use createdWithin ou os limites absolutos, nunca ambos.
`invalid_created_within`	400	não	Use uma duração positiva terminada em m, h, d ou w.
`timezone_required`	400	não	Inclua o offset UTC em createdFrom e createdTo.
`invalid_date_range`	400	não	Faça createdFrom ser anterior ou igual a createdTo.
`invalid_distributor_login`	400	não	Use e-mail CELESC ou CPF/CNPJ COPEL no formato exigido.
`invalid_distributor_credentials`	401	não	Reautorize o mesmo connectionId com a senha correta.
`connection_not_found`	404	não	Confirme connectionId e a chave do mesmo cliente.
`connection_account_mismatch`	409	não	Use o login pertencente à conexão ou autorize sem connectionId.
`connection_distributor_mismatch`	400	não	Faça dist corresponder à conexão.
`invalid_job_type`	400	não	Use um tipo documentado.
`invalid_job_payload`	400	não	Envie os seletores exigidos pelo tipo.
`invalid_uc`	400	não	Envie somente dígitos ASCII.
`missing_uc`	400	não	Informe uc ou um alias aceito na rota de faturas.
`uc_not_found`	400	não	Confirme se a UC pertence à conexão.
`invalid_billing_period`	400	não	Use YYYY-MM e um intervalo válido.
`invalid_pdf_source`	400	não	Em POST /pdf/parse, envie somente invoice ou somente url.
`invalid_pdf_url`	400	não	Use uma URL HTTP/HTTPS pública, sem credenciais, fragmento ou endereço privado.
`pdf_too_large`	413	não	Envie um PDF dentro do limite informado pela API.
`invalid_pdf`	422	não	Envie um PDF não vazio e legível.
`protected_pdf`	422	não	Remova a senha do PDF antes de enviá-lo.
`unsupported_invoice_pdf`	422	não	Envie uma fatura textual da CELESC ou COPEL.
`job_not_found`	404	não	Confirme jobId e o cliente autenticado.
`installation_not_found`	404	não	Confira a UC ou execute uc_discovery.
`invoice_not_found`	404	não	Confira invoiceId, período e UC.
`job_already_exists`	409	não	Consulte details.jobId.
`job_not_cancellable`	409	não	Leia o resultado do trabalho terminal.
`reauth_required`	409	não	Reautorize com o mesmo connectionId.
`job_limit_exceeded`	429	sim	Aguarde trabalhos ativos terminarem.
`active_uc_limit_exceeded`	429	não	Use uma UC já ativa ou ajuste o limite contratado.
`quota_service_unavailable`	503	sim	Aguarde e tente novamente.
`tenant_quota_exceeded`	429	não	Revise o limite contratado.
`distributor_rate_limited`	429	sim	Aguarde antes de repetir.
`distributor_unavailable`	503	sim	Aguarde e tente novamente.
`distributor_error`	502	não	Revise o alvo e, se persistir, envie X-Request-Id ao suporte.
`pdf_parse_failed`	422	não	Registre invoiceId, quando houver, e X-Request-Id; solicite análise do documento.
`pdf_download_failed`	502	sim	Confira se a URL está pública; se estiver, aguarde e tente novamente.
`job_timeout`	504	sim	Processe itens parciais e repita apenas o alvo ausente.
`internal_error`	500	sim	Tente novamente; se persistir, envie X-Request-Id ao suporte.

Como repetir com segurança

Para erros repetíveis, use espera crescente e um limite de tentativas. Não repita imediatamente em loop. Para erros não repetíveis, altere o payload, a credencial ou o estado indicado.

Use `X-Request-Id`

Toda resposta inclui um identificador de requisição. Guarde-o com endpoint, horário, HTTP, jobId e error.code para diagnóstico e suporte.

Formato do erro

Todos os códigos públicos

Como repetir com segurança

Use X-Request-Id

Use `X-Request-Id`