API Receita Saúde · v2.1
Referência de Erros
Lista completa de todos os códigos de erro retornados pela API, agrupados por endpoint.
Todos os erros retornam um JSON com os campos
error_code e error_message. O código HTTP indica a categoria do erro:4xx erros do cliente · 5xx erros internos do servidor./receipts| Código | HTTP | Descrição |
|---|---|---|
| RECEIPT_ERROR_001 | 400 | O campo 'identificador' não corresponde ao token de acesso utilizado. |
| RECEIPT_ERROR_002 | 400 | Corpo da requisição ausente ou inválido. |
| RECEIPT_ERROR_003 | 400 | O campo 'test' deve ser booleano (true ou false). |
| RECEIPT_ERROR_004 | 400 | O campo 'action' é obrigatório. |
| RECEIPT_ERROR_005 | 400 | O campo 'issuer_code' é obrigatório. |
| RECEIPT_ERROR_006 | 404 | Emissor não encontrado para o identificador informado. |
| RECEIPT_ERROR_007 | 403 | O emissor está desativado. Ative-o antes de emitir recibos. |
| RECEIPT_ERROR_008 | 403 | Certificado digital expirado. Faça o upload de um certificado válido. |
| RECEIPT_ERROR_009 | 400 | Ação não suportada. Use 'issue' ou 'cancel'. |
| RECEIPT_ERROR_010 | 400 | Campos obrigatórios ausentes na requisição. |
| RECEIPT_ERROR_011 | 400 | O campo 'reason' só é permitido quando a ação for 'cancel'. |
| RECEIPT_ERROR_012 | 400 | CPF do pagador inválido. |
| RECEIPT_ERROR_013 | 400 | O CPF do pagador não pode ser igual ao CPF do emissor. |
| RECEIPT_ERROR_014 | 400 | CPF do beneficiário inválido. |
| RECEIPT_ERROR_015 | 400 | O campo 'amount' deve ser um número (não uma string). |
| RECEIPT_ERROR_016 | 400 | O valor informado excede o máximo permitido de 99.999.999,99. |
| RECEIPT_ERROR_017 | 400 | O campo 'date' não pode ser uma data futura. |
| RECEIPT_ERROR_018 | 400 | O campo 'date' deve estar no formato ISO 8601 válido. |
| RECEIPT_ERROR_019 | 400 | Código de ocupação (occupation_code) inválido. |
| RECEIPT_ERROR_020 | 400 | O campo 'occupation_code' deve ser um número inteiro. |
| RECEIPT_ERROR_021 | 404 | Cancelamento não realizado: recibo não encontrado. |
| RECEIPT_ERROR_022 | 400 | O recibo já foi cancelado ou está em processo de cancelamento. |
| RECEIPT_ERROR_023 | 409 | Já existe um recibo com este receipt_id e issuer_code. |
| RECEIPT_ERROR_024 | 400 | Erro de validação nos dados do recibo. |
| RECEIPT_ERROR_025 | 500 | Erro interno no banco de dados ao salvar o recibo. |
| RECEIPT_ERROR_026 | 403 | Nenhum certificado registrado. Faça o upload antes de emitir recibos. |
| RECEIPT_ERROR_027 | 403 | Nenhum endpoint de callback registrado. Registre um antes de emitir recibos. |
/issuers| Código | HTTP | Descrição |
|---|---|---|
| ISSUERS_ERROR_001 | 400 | Corpo JSON vazio ou inválido. |
| ISSUERS_ERROR_002 | 400 | Content-Type deve ser application/json. |
| ISSUERS_ERROR_003 | 400 | O campo 'identificador' não corresponde ao token de acesso utilizado. |
| ISSUERS_ERROR_005 | 400 | Código de ocupação (occupation_code) inválido. |
| ISSUERS_ERROR_006 | 400 | Ação inválida. Use 'enable' ou 'disable'. |
| ISSUERS_ERROR_007 | 400 | O campo 'issuer_code' é obrigatório. |
| ISSUERS_ERROR_008 | 404 | Emissor não encontrado ao tentar desativar. |
| ISSUERS_ERROR_009 | 500 | Erro interno ao desativar o emissor no banco de dados. |
| ISSUERS_ERROR_010 | 400 | CPF do emissor em formato inválido. |
| ISSUERS_ERROR_011 | 400 | CPF é obrigatório ao criar um novo emissor. |
| ISSUERS_ERROR_012 | 400 | O campo 'occupation_code' é obrigatório ao criar um novo emissor. |
| ISSUERS_ERROR_013 | 500 | Erro interno ao salvar o emissor no banco de dados. |
| ISSUERS_ERROR_014 | 400 | O campo 'registration' é obrigatório ao criar um novo emissor. |
/endpoint| Código | HTTP | Descrição |
|---|---|---|
| ENDPOINT_ERROR_001 | 400 | O corpo da requisição deve estar em formato JSON. |
| ENDPOINT_ERROR_002 | 400 | Os campos 'url' e 'token' são obrigatórios. |
| ENDPOINT_ERROR_003 | 500 | Erro interno ao registrar o endpoint de callback. |
| ENDPOINT_ERROR_004 | 400 | O campo 'identificador' não corresponde ao token de acesso utilizado. |
/client/certificate| Código | HTTP | Descrição |
|---|---|---|
| CLIENT_CERT_ERROR_000 | 400 | O campo 'identificador' não corresponde ao token de acesso utilizado. |
| CLIENT_CERT_ERROR_001 | 404 | Cliente não encontrado. |
| CLIENT_CERT_ERROR_002 | 400 | O arquivo de certificado e a senha são obrigatórios. |
| CLIENT_CERT_ERROR_003 | 400 | Certificado ou senha inválidos. |
| CLIENT_CERT_ERROR_004 | 500 | Erro ao fazer upload do certificado para o armazenamento. |
| CLIENT_CERT_ERROR_005 | 500 | Erro interno ao atualizar os dados do certificado no banco de dados. |
/auth/token| Código | HTTP | Descrição |
|---|---|---|
| AUTH_ERROR_001 | 400 | Campos obrigatórios ausentes: identificador e master_key. |
| AUTH_ERROR_002 | 401 | Identificador ou master_key inválidos. |
ISSUE_ERROR_* · Callback
Estes códigos não são retornados na resposta HTTP da API — a requisição já foi aceita com sucesso. São gerados pelo sistema de processamento (fora desta API) que se comunica diretamente com a Receita Federal, e chegam de forma assíncrona no campo status_message do payload de callback, quando success: false, como uma única string no formato "ISSUE_ERROR_{código}: mensagem".
Erros de Certificado Digital
| Código | status_message recebido / Causa e solução |
|---|---|
| 30 | "ISSUE_ERROR_30: Certificado digital expirado"O certificado digital do cliente expirou e não é mais aceito pela Receita Federal. Atualize o certificado digital do cliente via /client/certificate. |
| 31 | "ISSUE_ERROR_31: Procuração não concedida ou expirada. Verifique o status da procuração deste emitente."A procuração eletrônica do emitente junto à Receita Federal não foi outorgada ou está vencida. Verifique e renove a procuração no portal da Receita Federal. |
| 35 | "ISSUE_ERROR_35: Corrupted digital certificate"O certificado digital está corrompido e não pode ser utilizado para autenticação. Reenvie um certificado digital válido via /client/certificate. Mensagem enviada em inglês pelo sistema de processamento, diferente dos demais códigos desta faixa. |
| 39 | "ISSUE_ERROR_39: Verificação em duas etapas ativada para acesso ao serviço da Receita Federal"A conta do emitente possui verificação em duas etapas ativada, bloqueando o acesso automatizado ao Carnê-Leão Web. Desative a verificação em duas etapas no portal da Receita Federal. |
Erros de Cadastro na RFB
| Código | status_message recebido / Causa e solução |
|---|---|
| 40 | "ISSUE_ERROR_40: Identificação ou configuração do emitente ausentes"Dados de identificação ou configuração do emitente estão incompletos no sistema. Verifique o cadastro do emitente. |
| 42 | "ISSUE_ERROR_42: Receita Saúde não está disponível no Carnê Leão Web para este emitente"O módulo Receita Saúde não está habilitado no Carnê-Leão Web para este emitente. Verifique a habilitação junto à Receita Federal. |
| 43 | "ISSUE_ERROR_43: Nenhum registro profissional foi encontrado para a atividade"Nenhum registro profissional cadastrado foi encontrado para a atividade/ocupação informada. Confirme o registro ativo no conselho profissional correspondente. |
| 44 | "ISSUE_ERROR_44: Não foi possível localizar o registro deste emitente no Carnê-Leão Web"O cadastro do emitente não foi localizado no Carnê-Leão Web. Verifique se o emitente está devidamente registrado junto à Receita Federal. |
| 45 | "ISSUE_ERROR_45: Registro profissional não confere com o fornecido pelo conselho profissional"O número de registro profissional informado diverge do que consta no conselho profissional. Corrija o número de registro do emitente. |
| 46 | "ISSUE_ERROR_46: CPF do profissional inválido"O CPF do profissional (emitente) informado é inválido perante a Receita Federal. Verifique o CPF cadastrado do emitente. |
Erros de Emissão
| Código | status_message recebido / Causa e solução |
|---|---|
| 50 | "ISSUE_ERROR_50: O pagador é inválido ou seu CPF não existe na base de dados da Receita Federal"O CPF do pagador não existe ou não está regular na base da Receita Federal. Verifique o CPF do pagador diretamente nos canais da Receita Federal. |
| 51 | "ISSUE_ERROR_51: O beneficiário é inválido ou seu CPF não existe na base de dados da Receita Federal"O CPF do beneficiário não existe ou não está regular na base da Receita Federal. Verifique o CPF do beneficiário diretamente nos canais da Receita Federal. |
| 52 | "ISSUE_ERROR_52: A emissão de recibos para o ano calendário informado não é mais permitida pela Receita Federal"O prazo estabelecido pela Receita Federal para emissão de recibos referentes ao ano-calendário informado já se encerrou. |
| 53 | "ISSUE_ERROR_53: O valor do lançamento deve ser maior que 0."O campo amount do recibo foi enviado como zero ou negativo. Envie um valor de lançamento maior que zero. |
| 54 | "ISSUE_ERROR_54: Código de Ocupação inválido"O occupation_code informado não é um código de ocupação permitido pela Receita Federal. Utilize um dos códigos de ocupação válidos. |
| 55 | "ISSUE_ERROR_55: Data posterior à data corrente"A data informada no campo date do recibo é posterior à data atual e foi rejeitada pela Receita Federal. Envie uma data retroativa ou atual. |
| 56 | "ISSUE_ERROR_56: Código de Ocupação não vinculado ao emitente"O occupation_code informado na emissão não está vinculado ao cadastro do emitente na Receita Federal. Verifique se o código corresponde a um registro profissional ativo e vinculado ao emitente no Carnê-Leão Web. |
Erros de Cancelamento
| Código | status_message recebido / Causa e solução |
|---|---|
| 60 | "ISSUE_ERROR_60: O prazo para cancelamento deste recibo já expirou"O prazo para cancelamento do recibo junto à Receita Federal foi ultrapassado. Não é possível cancelar o recibo após o prazo estabelecido. |
Documentação da API Rebots · Versão 2.1
Última atualização: 12 de março de 2026