---
title: "Errors"
description: "How Amplia's API reports errors: HTTP status codes, the ErrorModel body with its error code, what the client libraries throw, and error codes seen in the samples and demos."
canonical: "https://docs.lacunasoftware.com/en-us/articles/amplia/integration/errors"
locale: "en"
product: "Amplia"
last_updated: "2026-10-12"
---

# Errors

## HTTP status codes

[Amplia](https://docs.lacunasoftware.com/en-us/articles/amplia)'s API answers with an HTTP status code: 

| Status | Meaning |
|---|---|
| 200 OK | The request was processed; the body depends on the operation. |
| 400 Bad Request | Syntax error, for instance a required field is missing. |
| 401 Unauthorized | The API key was not sent or is invalid. |
| 403 Forbidden | The API key is valid, but the application lacks the permission for the operation. |
| 422 Unprocessable Entity | API error, for instance an entity id that is not found; the body is an `ErrorModel`. |
| 500 Internal Server Error | Unexpected error; the `exceptionCode` in the body helps Lacuna support diagnose it. |

## The error body

An `ErrorModel` has a `code`, a `message` and `details`. The messages don't follow the `Accept-Language` header: log them rather than show
them to users. 
The e-CPF demo shows users the error code, never the message, and treats Amplia's 4xx answers as refusals and anything else as a
failure. 

## What the client libraries throw

| Client | API error (422) | Other HTTP errors | Endpoint unreachable |
|---|---|---|---|
| Node.js | `AmpliaError`, whose `code` is the error code; `OrderLocketError` when the code is `OrderLocked` | `RestError`, whose `code` is the HTTP status | `RestUnreachableError` |
| Java | `RestErrorException`, with the status and the message but not the error code | `RestErrorException`, or `RestResourceNotFoundException` for some 404 responses | `RestUnreachableException` |
| PHP | `AmpliaException` (`getErrorCode()`, `getErrorMessage()`); `OrderLockedException` when the code is `OrderLocked` | `RestErrorException` (`getStatusCode()`) | `RestUnreachableException` |
| Python | `RestError`, with only the HTTP status (see below) | `RestError` | `RestUnreachableError` |
| .NET | `AmpliaException` (`Code`, `CodeStr`, `ErrorMessage`); `OrderLockedException` when the code is `OrderLocked` | `RestException` from `Lacuna.RestClient` | |

The Python client 1.0.0 defines `AmpliaError` and `OrderLockedError` for 422 responses, but its error handling reads the code from the
wrong object, so every error response comes out as `RestError` with only the HTTP status. 

## Error codes

The API's `ErrorCodes` enum, which the .NET client exposes as `AmpliaException.Code`, has 160 codes in Amplia 5.0.1; the Node.js and
PHP clients list 95 of them (`AmpliaErrorCodes` in Node.js, `ErrorCodes` in PHP). 
These are the ones that the calls in this guide return, with what Amplia 5.0.1 means by each: 

| Area | Code | Meaning |
|---|---|---|
| Orders | `OrderNotFound` | No order with that id (or, on the issue page, with that secret). |
| | `OrderDeleted` | The order was deleted. |
| | `OrderAlreadyFulfilled` | The order's certificate was already issued: it can't be issued again, deleted, or have its link sent. |
| | `OrderLocked` | The order is locked. |
| | `CARequired` | No `caId` was sent and the application has no default CA. |
| | `CANotFound`, `TemplateNotFound` | No CA, or no template, with that id. |
| | `CANotActive` | The CA isn't active, so it can't issue. |
| | `NoSuitableTemplateFound` | The subscription has no template for the order's format. |
| | `ValidityRequired`, `KindRequired` | An order without a template needs `validityEnd` and `kind`; an order on a template with no default validity needs `validityEnd`. |
| | `ValidityStartRequired`, `BadValidityStart` | An order with `issuePendingApproval` needs a `validityStart` in the future. |
| | `TemplateForbidsCustomValidity`, `TemplateForbidsParameter` | The template doesn't let the order set its validity, or that parameter. |
| | `CertificateKindNotSupported` | The `kind` (public-key or attribute) doesn't match what the CA or the template issues. |
| | `BadOrderParameters` | A parameter is missing or not allowed by the template. |
| | `InvalidCpf`, `InvalidCnpj`, `InvalidPhoneNumber` | The CPF, CNPJ or phone number is not valid. |
| | `DnsNamesRequired`, `BadDnsName` | An SSL/TLS order has no DNS name, or one that is not valid. |
| Issuance | `CsrRequired` | A public-key certificate needs a CSR (or a key held by Amplia). |
| | `CsrNotExpected` | An attribute certificate takes no CSR or key. |
| | `BadCsr` | The CSR is not valid. |
| | `KeySizeNotSupported`, `BadKeySize` | The key size is not valid, or is below the template's minimum. |
| | `DigestAlgorithmNotSupported` | The digest algorithm is not supported. |
| Issue link | `NoEmailAddress`, `EmailDisabled` | The order has no email address, or the instance can't send email. |
| | `NoPhoneNumber`, `SmsDisabled` | The order has no phone number, or the instance can't send SMS. |
| | `IssueSessionExpired`, `NoMoreConfirmAttemptsRemaining` | During issuance on Amplia's issue page: the session expired, or the holder used up the attempts to type the code sent by SMS. |
| Certificates | `CertificateNotFound` | No certificate with that id. |
| | `CertificateAlreadyRevoked` | The certificate was already revoked. |

A permission the application lacks is answered with 403 Forbidden, not with an error code: in Amplia 5.0.1, no call returns the
`AccessDeniedTo…` codes that the clients list. 

The SSL/TLS demo maps `BadDnsName` and `BadCsr` to messages of its own. 

## See also

* [Integration guide](https://docs.lacunasoftware.com/en-us/articles/amplia/integration)
* [Amplia quick reference](https://docs.lacunasoftware.com/en-us/articles/amplia/quick-reference#errors)