---
title: "Erros"
description: "Como a API do Amplia informa erros: códigos de status HTTP, o corpo ErrorModel com o código de erro, o que as bibliotecas cliente lançam e os códigos de erro vistos nos samples e nas demos."
canonical: "https://docs.lacunasoftware.com/articles/amplia/integration/errors"
locale: "pt-BR"
product: "Amplia"
last_updated: "2026-10-12"
---

# Erros

## Códigos de status HTTP

A API do [Amplia](https://docs.lacunasoftware.com/articles/amplia) responde com um código de status HTTP: 

| Status | Significado |
|---|---|
| 200 OK | A requisição foi processada; o corpo depende da operação. |
| 400 Bad Request | Erro de sintaxe, por exemplo, um campo obrigatório ausente. |
| 401 Unauthorized | A chave de API não foi enviada ou é inválida. |
| 403 Forbidden | A chave de API é válida, mas a aplicação não tem permissão para a operação. |
| 422 Unprocessable Entity | Erro de API, por exemplo, o id de uma entidade que não é encontrada; o corpo é um `ErrorModel`. |
| 500 Internal Server Error | Erro inesperado; o `exceptionCode` no corpo ajuda o suporte da Lacuna no diagnóstico. |

## O corpo do erro

Um `ErrorModel` tem `code`, `message` e `details`. As mensagens não seguem o header `Accept-Language`: registre-as no log em vez de
mostrá-las aos usuários. 
A demo de e-CPF mostra aos usuários o código de erro, nunca a mensagem, e trata as respostas 4xx do Amplia como recusas e qualquer outra
coisa como falha. 

## O que as bibliotecas cliente lançam

| Cliente | Erro de API (422) | Outros erros HTTP | Endpoint inacessível |
|---|---|---|---|
| Node.js | `AmpliaError`, cujo `code` é o código de erro; `OrderLocketError` quando o código é `OrderLocked` | `RestError`, cujo `code` é o status HTTP | `RestUnreachableError` |
| Java | `RestErrorException`, com o status e a mensagem, mas sem o código de erro | `RestErrorException`, ou `RestResourceNotFoundException` em algumas respostas 404 | `RestUnreachableException` |
| PHP | `AmpliaException` (`getErrorCode()`, `getErrorMessage()`); `OrderLockedException` quando o código é `OrderLocked` | `RestErrorException` (`getStatusCode()`) | `RestUnreachableException` |
| Python | `RestError`, só com o status HTTP (veja abaixo) | `RestError` | `RestUnreachableError` |
| .NET | `AmpliaException` (`Code`, `CodeStr`, `ErrorMessage`); `OrderLockedException` quando o código é `OrderLocked` | `RestException` do `Lacuna.RestClient` | |

O cliente Python 1.0.0 define `AmpliaError` e `OrderLockedError` para respostas 422, mas o tratamento de erros dele lê o código do objeto
errado, então toda resposta de erro vira `RestError` só com o status HTTP. 

## Códigos de erro

O enum `ErrorCodes` da API, que o cliente .NET expõe como `AmpliaException.Code`, tem 160 códigos no Amplia 5.0.1; os clientes Node.js e
PHP listam 95 deles (`AmpliaErrorCodes` no Node.js, `ErrorCodes` no PHP). 
Estes são os que as chamadas deste guia devolvem, com o que o Amplia 5.0.1 quer dizer com cada um: 

| Área | Código | Significado |
|---|---|---|
| Pedidos | `OrderNotFound` | Não há pedido com esse id (ou, na página de emissão, com esse segredo). |
| | `OrderDeleted` | O pedido foi excluído. |
| | `OrderAlreadyFulfilled` | O certificado do pedido já foi emitido: ele não pode ser emitido de novo, nem excluído, nem ter o link enviado. |
| | `OrderLocked` | O pedido está bloqueado. |
| | `CARequired` | Nenhum `caId` foi enviado e a aplicação não tem AC padrão. |
| | `CANotFound`, `TemplateNotFound` | Não há AC, ou modelo, com esse id. |
| | `CANotActive` | A AC não está ativa, então não pode emitir. |
| | `NoSuitableTemplateFound` | A conta não tem modelo para o formato do pedido. |
| | `ValidityRequired`, `KindRequired` | Um pedido sem modelo precisa de `validityEnd` e `kind`; um pedido em um modelo sem validade padrão precisa de `validityEnd`. |
| | `ValidityStartRequired`, `BadValidityStart` | Um pedido com `issuePendingApproval` precisa de um `validityStart` no futuro. |
| | `TemplateForbidsCustomValidity`, `TemplateForbidsParameter` | O modelo não deixa o pedido definir a validade, ou esse parâmetro. |
| | `CertificateKindNotSupported` | O `kind` (chave pública ou atributo) não corresponde ao que a AC ou o modelo emite. |
| | `BadOrderParameters` | Falta um parâmetro, ou o modelo não o permite. |
| | `InvalidCpf`, `InvalidCnpj`, `InvalidPhoneNumber` | O CPF, o CNPJ ou o telefone não é válido. |
| | `DnsNamesRequired`, `BadDnsName` | Um pedido SSL/TLS não tem nome DNS, ou tem um que não é válido. |
| Emissão | `CsrRequired` | Um certificado de chave pública precisa de um CSR (ou de uma chave guardada no Amplia). |
| | `CsrNotExpected` | Um certificado de atributo não recebe CSR nem chave. |
| | `BadCsr` | O CSR não é válido. |
| | `KeySizeNotSupported`, `BadKeySize` | O tamanho de chave não é válido, ou é menor que o mínimo do modelo. |
| | `DigestAlgorithmNotSupported` | O algoritmo de hash não é suportado. |
| Link de emissão | `NoEmailAddress`, `EmailDisabled` | O pedido não tem endereço de e-mail, ou a instância não pode enviar e-mail. |
| | `NoPhoneNumber`, `SmsDisabled` | O pedido não tem telefone, ou a instância não pode enviar SMS. |
| | `IssueSessionExpired`, `NoMoreConfirmAttemptsRemaining` | Durante a emissão na página de emissão do Amplia: a sessão expirou, ou o titular esgotou as tentativas de digitar o código enviado por SMS. |
| Certificados | `CertificateNotFound` | Não há certificado com esse id. |
| | `CertificateAlreadyRevoked` | O certificado já foi revogado. |

Uma permissão que falta à aplicação é respondida com 403 Forbidden, e não com um código de erro: no Amplia 5.0.1, nenhuma chamada devolve
os códigos `AccessDeniedTo…` que os clientes listam. 

A demo de SSL/TLS traduz `BadDnsName` e `BadCsr` em mensagens próprias. 

## Veja também

* [Guia de integração](https://docs.lacunasoftware.com/articles/amplia/integration)
* [Referência rápida do Amplia](https://docs.lacunasoftware.com/articles/amplia/quick-reference#erros)