Erros

Códigos de status HTTP

A API do 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
• Referência rápida do Amplia