# Códigos de erro Todas as respostas de erro seguem o formato `{ "error": { "code", "message", "status", "details" } }`. Erros de validação incluem um array `details` com códigos e parâmetros estruturados por campo. #### Autenticação e autorização | Código | HTTP | Descrição | | --------------------------------- | ---- | ----------------------------------------------- | | `MISSING_AUTH_CREDENTIALS` | 401 | Header `x-api-key` ausente ou inválido. | | `INVALID_TOKEN` | 401 | Token expirado ou malformado. | | `ONLY_ACTIVE_INTEGRATION_ALLOWED` | 401 | A integração está inativa. | | `INVALID_IP_RANGE` | 401 | IP do chamador fora da allowlist da integração. | | `PERMISSION_DENIED` | 403 | Sem permissão para este recurso/ação. | #### NFS-e — emissão | Código | HTTP | Descrição | | -------------------------------------------- | ---- | ------------------------------------------------------------------ | | `VALIDATION_ERROR` | 400 | Payload com campos inválidos (veja `details[]`). | | `NFSE_CERTIFICATE_REQUIRED` | 400 | Empresa sem certificado cadastrado. | | `NFSE_CERTIFICATE_EXPIRED` | 400 | Certificado expirado. | | `NFSE_CERTIFICATE_EXPIRATION_MISSING` | 400 | Data de expiração não encontrada no certificado. | | `NFSE_CERTIFICATE_PASSWORD_MISSING` | 400 | Senha do certificado não informada. | | `NFSE_CERTIFICATE_FILE_MISSING` | 400 | Arquivo do certificado não encontrado. | | `NFSE_INTEGRATION_MISSING` | 400 | Empresa sem `nfse_config.integration` configurada. | | `NFSE_PROFILE_CODE_MISSING` | 400 | Código do profile NFS-e não encontrado para o município. | | `NFSE_ISSUER_MUNICIPAL_REGISTRATION_MISSING` | 400 | Inscrição municipal ausente (obrigatória para provider municipal). | | `NFSE_COMPANY_SERIES_MISSING` | 422 | Empresa sem série fiscal configurada para o provider selecionado. | | `NFSE_DOCUMENT_REFERENCE_INVALID` | 400 | Referência a documento inválida (substituição). | | `NFSE_DOCUMENT_PAYLOAD_INVALID` | 400 | Payload de documento inválido após validação do profile. | | `NFSE_SUBSTITUTION_NOT_SUPPORTED` | 400 | Provider não suporta substituição. | | `NFSE_BATCH_SUBSTITUTION_INVALID` | 400 | Requisição de substituição com documentos inválidos. | | `NFSE_ISSUERS_NOT_FOUND` | 404 | Emissores não encontrados no workspace. | | `NFSE_CERTIFICATE_NOT_FOUND` | 404 | Certificado não encontrado para o emissor. | | `NFSE_PROFILE_CONFIG_NOT_FOUND` | 404 | Configuração do profile não encontrada para o município/provider. | | `NFSE_EXTERNAL_ID_ALREADY_EXISTS` | 409 | `external_id` já utilizado por outra NFS-e ativa. | | `NFSE_NOT_FOUND` | 404 | NFS-e não encontrada. | #### NFS-e — operações | Código | HTTP | Descrição | | --------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NFSE_BATCH_RESEND_INVALID` | 400 | Requisição contém NFS-e em status não permitido para reenvio. | | `NFSE_BATCH_CANCEL_INVALID` | 422 | Requisição contém NFS-e em status não permitido para cancelamento. | | `NFSE_CANCELLATION_NOT_SUPPORTED` | 400 | Provider não suporta cancelamento. | | `NFSE_CANCEL_NUMBER_MISSING` | 400 | Número da NFS-e ausente (obrigatório para cancelar). | | `NFSE_VALIDATION_FAILED` | 400 | Falha estrutural de contrato HTTP, como campo operacional fora do payload público. Regras fiscais de obrigatoriedade, tamanho, faixa e domínio ficam para rejeição oficial do provedor/prefeitura. | | `NFSE_SYNC_INVALID` | 400 | NFS-e em status não permitido para sincronização. | | `NFSE_SYNC_REFERENCE_MISSING` | 400 | Referência fiscal ausente para sincronizar ou reconciliar. | #### NFCom — emissão | Código | HTTP | Descrição | | ---------------------------------- | ---- | ------------------------------------------------- | | `NFCOM_CERTIFICATE_REQUIRED` | 400 | Empresa sem certificado cadastrado. | | `NFCOM_CERTIFICATE_EXPIRED` | 400 | Certificado expirado. | | `NFCOM_ISSUER_NOT_FOUND` | 404 | Emissor não encontrado no workspace. | | `NFCOM_ISSUER_UF_MISSING` | 400 | UF do emissor ausente. | | `NFCOM_EXTERNAL_ID_ALREADY_EXISTS` | 409 | `external_id` já utilizado por outra NFCom ativa. | | `NFCOM_NOT_FOUND` | 404 | NFCom não encontrada. | #### NFCom — operações | Código | HTTP | Descrição | | ---------------------------- | ---- | ------------------------------------------------- | | `NFCOM_BATCH_CANCEL_INVALID` | 400 | NFCom em status não permitido para cancelamento. | | `NFCOM_BATCH_SYNC_INVALID` | 400 | NFCom em status não permitido para sincronização. | #### Empresas | Código | HTTP | Descrição | | ---------------------------------- | ---- | ------------------------------------------------------------- | | `INVALID_COMPANY_REFERENCE_FORMAT` | 400 | Referência deve ser ObjectId ou CNPJ de 14 dígitos. | | `COMPANY_NOT_FOUND` | 404 | Empresa não encontrada no workspace. | | `COMPANY_REFERENCE_MISMATCH` | 400 | `company_id` do payload diverge da empresa vinculada à chave. | #### Certificados | Código | HTTP | Descrição | | ------------------------------------ | ---- | ---------------------------------------------- | | `CERTIFICATE_FILE_REQUIRED` | 400 | Arquivo `.p12` / `.pfx` obrigatório. | | `CERTIFICATE_INVALID_PASSWORD` | 400 | Senha incorreta para o certificado. | | `CERTIFICATE_EXPIRED` | 400 | Certificado com data de validade ultrapassada. | | `CERTIFICATE_INVALID_FILE_EXTENSION` | 400 | Extensão do arquivo não é `.p12` nem `.pfx`. | | `CERTIFICATE_NOT_FOUND` | 404 | Certificado não encontrado. | | `CERTIFICATE_IN_USE` | 409 | Certificado em uso por empresa ativa. | #### Integrações e webhooks | Código | HTTP | Descrição | | ---------------------------------------- | ---- | ------------------------------------------- | | `INTEGRATION_NOT_FOUND` | 404 | Integração não encontrada. | | `INTEGRATION_MUST_BE_INACTIVE_TO_DELETE` | 409 | Desative a integração antes de excluir. | | `WEBHOOK_MUST_BE_INACTIVE_TO_DELETE` | 409 | Desative o webhook antes de excluir. | | `WEBHOOK_MUST_BE_ACTIVE_TO_TEST` | 400 | Webhook deve estar ativo para enviar teste. | | `WEBHOOK_EVENT_NOT_CONFIGURED` | 400 | Evento não configurado neste webhook. | #### Referências | Código | HTTP | Descrição | | ---------------------------- | ---- | ---------------------------- | | `POSTAL_CODE_INVALID_FORMAT` | 400 | CEP deve conter 8 dígitos. | | `POSTAL_CODE_NOT_FOUND` | 404 | CEP não encontrado. | | `CNPJ_INVALID_FORMAT` | 400 | CNPJ deve conter 14 dígitos. | | `CNPJ_NOT_FOUND` | 404 | CNPJ não encontrado. | #### Genéricos | Código | HTTP | Descrição | | ----------------------- | ---- | ------------------------------------------------------------------------------ | | `INTERNAL_SERVER_ERROR` | 500 | Erro interno. Tente novamente e, se persistir, entre em contato com o suporte. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ixc-soft.gitbook.io/e-docs/codigos-de-erro.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.