Error codes - Amplia Reg

When a call to the Amplia Reg API fails because of how it was made, for example a missing field or an order in the wrong status, the API responds with HTTP code 422 (Unprocessable Entity) and an ErrorModel in the body. In .NET, the client throws an AmpliaRegException. In both cases, the error code identifies the problem. See HTTP response codes for the format.

{
	"code": "OrderNotFound",
	"message": "Order not found"
}

Use the code field to decide what to do. The message field helps diagnose the problem and should be logged, not shown to the user: it is always in English and its wording may change.

The tables below list the codes you are most likely to get when calling the APIs described in this Integration Guide, grouped by topic.

Registration authority

Code	When it happens
`RegistrationAuthorityRequired`	The order creation request did not say at which registration authority to create the order: send `registrationAuthority` in the body
`RegistrationAuthorityNotFound`	The registration authority given in the request does not exist
`SubscriptionRequired`	The request needs a registration authority in the `X-Subscription` header, as when creating preapproved orders, and none was sent
`NormalSubscriptionRequired`	The `X-Subscription` header named the root subscription instead of a registration authority
`CertificationAuthorityMismatch`	The certificate type belongs to a different certification authority than the registration authority

Certificate type and holder type

Code	When it happens
`CertificateTypeNotFound`	No certificate type with the given `code` or `id` exists for the certification authority
`BadCertificateTypeReference`	`certificateType` has neither `code` nor `id`
`CertificateTypeDisabled`	The certificate type is disabled
`CertificateFormatMismatch`	The certificate type has a different format from the route called, for example an SSL certificate type on `/api/brazil/orders`
`HolderTypeNotFound`	No holder type with the given `code` or `id` exists
`BadHolderTypeReference`	`holderType` has neither `code` nor `id`
`HolderTypeDisabled`	The holder type is disabled
`HolderTypeNotAllowed`	The certificate type does not accept the given holder type, or does not accept holder types at all
`HolderTypeIsRequired`	The certificate type accepts more than one holder type and `holderType` was not given
`InvalidValidityOption`	The certificate type does not offer the given validity
`ValidityIsRequired`	The certificate type has more than one validity option and `validity` was not given

Order data

Code	When it happens
`InvalidParams`	A required holder field is missing. For an ICP-Brasil organizational certificate (e-CNPJ): `organizationName` or `cnpj`
`CustomNumberNotAllowed`	`number` was sent, but the instance does not allow custom order numbers
`OrderNumberAlreadyExists`	Another order already has the given `number`
`SaleNumberNotAllowed`	`saleNumber` was sent, but the instance does not use sale numbers
`SaleNumberIsRequired`	The instance requires `saleNumber` and it was not sent
`PrimaryEmailInUseForAnotherPerson`, `AlternativeEmailInUseForAnotherPerson`, `BothEmailsInUseForAnotherPerson`	The instance allows only one person per email address, and an email address in `contact` already belongs to another holder
`SelfOperationDenied`	The instance does not allow agents to act on their own orders, and the holder is the user making the call
`OrderCreationDisabled`	The instance does not allow users to create orders. Applications are not affected
`InvalidCsr`	The CSR sent could not be decoded

Issue type

Code	When it happens
`InvalidIssueType`	`issueType` is `PreApproved`. Preapproved orders have their own API: see Creating preapproved orders
`CertificateTypeDoesNotAllowVideoConference`	`issueType` is `VideoConference`, but the certificate type does not allow videoconference
`CertificateTypeDoesNotAllowVideoIdentification`	`issueType` is `VideoIdentification`, but the certificate type does not allow video identification
`VideoConferenceDisabled`	Videoconference or video identification is not configured on the instance
`IssueTypeDoesNotAllowStartValidation`	`startValidation` was requested for an issue type that does not allow it

ICP-Brasil checks

Code	When it happens
`RfbQueryNotApproved`	The instance runs the RFB prior query when the order is created, and the query did not approve the holder's data. The message includes the reason returned by the query
`RfbQueryNameMismatch`	The name in the order is different from the name returned by the RFB query. Use the name returned by the query
`RfbQueryOrganizationNameMismatch`	The company name in the order is different from the one returned by the RFB query. Use the name returned by the query
`RfbQueryIsDisabled`	The RFB prior query API was called, but the RFB query is not configured on the instance
`PSBioDisabled`	The biometric enrollment check was called, but the biometric integration is not configured on the instance

Holder documents

Code	When it happens
`HolderFilesRequired`, `MissingRequiredHolderFileType`	A document required by the holder type is missing, or the photo, when the certificate type has the biometrics step enabled. The message lists the missing types
`InvalidHolderFileType`	A document type does not exist. Custom document types must be prefixed with `@`
`HolderFileTypeCannotBeAdded`	The holder type does not accept one of the document types sent
`CertificateTypeDoesNotAllowDocuments`	Documents were sent for a certificate type with the documents step disabled
`UnexpectedHolderFileSubtype`	The document type does not accept subtypes, or does not accept the given subtype
`MissingRequiredDocumentPart`	`subtype` was given without `documentPart`
`UnexpectedDocumentPart`	The `documentPart` is not allowed for the `subtype`

Existing orders

Code	When it happens
`OrderNotFound`	No order with the given number exists
`CannotCancelOrder`	The order cannot be canceled because it is already issued, revoked or canceled
`OrderCannotUpdate`	The order's data can no longer be changed because of its status, for example once it is waiting issue
`InvalidOrderStatus`	The operation is not allowed in the order's current status
`InvalidIssueType`	A preapproved order operation was called on an order that is not preapproved
`IssueKey1Disabled`	Issue key 1 was requested, but the instance uses a single issue key

note

The codes above are the ones most commonly returned by the APIs in this guide. The list is not comprehensive: other codes exist, and new codes may be added at any time without notice. Handle unknown codes as a generic failure, and log the message.

Registration authority​

Certificate type and holder type​

Order data​

Issue type​

ICP-Brasil checks​

Holder documents​

Existing orders​

See also​