Errors

HTTP status codes

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
• Amplia quick reference