Erros

Todas as falhas respondem com a mesma forma, para que tenha uma única coisa a interpretar:

json

{
  "Error": {
    "Code": "BUILDING_NOT_FOUND",
    "Message": "There is no condominium with that identifier.",
    "Field": "idBuilding"
  }
}

Campo	O que é
`Code`	Identificador estável da falha. É por aqui que deve decidir, nunca pela mensagem
`message`	Descrição em inglês, destinada a quem está a desenvolver e a registos de diagnóstico
`field`	O parâmetro ou campo em causa, quando existe um. `null` caso contrário

Decida pelo código

As mensagens podem ser reescritas sem aviso; os códigos não. Um switch sobre message parte-se na primeira melhoria de texto.

Estados HTTP

Estado	Quando acontece	O que fazer
`400`	O pedido está mal formado ou traz valores que não são aceites	Corrija o pedido. Repetir não ajuda
`401`	Problema com a credencial	Ver Autenticação
`403`	Credencial válida sem a área necessária	Ver Permissões
`404`	O registo indicado não existe nesta empresa	Confirme o identificador
`409`	Conflito com o que já existe	Ver a secção de conflitos abaixo
`422`	O pedido está correto mas a operação não pôde ser concluída	Depende do código. Ver abaixo
`429`	Excedeu o limite de pedidos	Espere e repita. Ver Limites
`500`	Erro inesperado do nosso lado (`INTERNAL_ERROR`)	Repita mais tarde; se persistir, reporte
`502`	O sistema que guarda as ocorrências desta empresa não respondeu	Repita daqui a pouco

Pedido inválido — `400`

Código	Significado
`INVALID_BODY`	O corpo do pedido falta ou não é JSON válido
`MISSING_FIELD`	Falta um campo obrigatório. `field` diz qual
`MISSING_CRITERIA`	Uma procura foi feita sem nenhum critério
`MISSING_DESCRIPTION`	A operação exige descrição e não veio nenhuma
`INVALID_CURSOR`	O cursor não é um que esta API tenha emitido
`CONFLICTING_FILTERS`	Dois parâmetros que não podem ser usados em conjunto
`UNSUPPORTED_FILTER`	Filtro desconhecido, ou não aplicável a esta empresa
`UNSUPPORTED_INCLUDE`	Foi pedida uma coleção que este ponto não sabe incluir
`UNSUPPORTED_FIELD`	Um campo do corpo não se aplica a esta empresa
`INVALID_TYPE`	Um identificador de tipo não corresponde a nenhum registado
`INVALID_STATUS`	O estado indicado não existe ou não se aplica
`INVALID_REFERENCE`	Um identificador de tabela de referência não é válido
`INVALID_PERIOD`	Datas de período incoerentes entre si
`INVALID_TAX_ID`	Número de contribuinte ausente ou inválido
`TOO_MANY_ATTACHMENTS`	Mais anexos do que o permitido
`DELIVERY_POINT_NOT_FOUND`	O ponto de entrega indicado não corresponde a nenhum contrato de consumo
`INVOICE_NOT_FOUND`	Uma fatura referida no corpo do pedido não existe
`INVALID_AMOUNT`	Um valor do corpo do pedido não é aceite, por exemplo igual ou inferior a zero

Filtros e include desconhecidos são recusados, não ignorados

Um include=intervention mal escrito responde UNSUPPORTED_INCLUDE em vez de ser lido como "não incluir". Assim um erro de escrita não passa por comportamento normal.

Não encontrado — `404`

BUILDING_NOT_FOUND, FRACTION_NOT_FOUND, OCCURRENCE_NOT_FOUND, CLAIM_NOT_FOUND, SUPPLIER_NOT_FOUND, INVOICE_NOT_FOUND, ENTRY_NOT_FOUND, REFERENCE_NOT_FOUND, ATTACHMENT_NOT_FOUND.

Todos significam o mesmo: não existe, nesta empresa, um registo com esse identificador. Note que identificadores não são comparáveis entre empresas.

Conflito — `409`

Código	Significado
`IDEMPOTENCY_KEY_REUSED`	A mesma chave de idempotência foi usada noutro pedido diferente. Ver Idempotência
`DOCUMENT_ALREADY_EXISTS`	Já existe um documento com esse número para esse fornecedor nesse ano
`INVOICE_ALREADY_SETTLED`	A fatura que tentou liquidar já estava liquidada

Um 409 não se resolve repetindo. DOCUMENT_ALREADY_EXISTS e INVOICE_ALREADY_SETTLED costumam significar que a operação já foi feita — confirme antes de tratar como falha.

Não foi possível concluir — `422`

O pedido estava correto; o estado da empresa é que não permite a operação.

Código	Significado	Resolve-se
`CLAIMS_NOT_CONFIGURED`	Esta empresa não tem os sinistros configurados	Na aplicação, pelo cliente
`MAINTENANCE_NOT_LICENSED`	A empresa não tem o módulo de manutenção licenciado	Comercialmente
`BUILDING_WITHOUT_MANAGER`	O condomínio não tem gestor atribuído	Na aplicação, pelo cliente
`BANK_ACCOUNT_NOT_DEFINED`	Falta a conta bancária necessária à operação	Na aplicação, pelo cliente
`OCCURRENCE_NOT_CREATED`	A ocorrência não chegou a ser criada	Reporte, com o pedido enviado
`INVOICE_NOT_CREATED`	A fatura não chegou a ser registada	Reporte
`PAYMENT_NOT_CREATED`	O pagamento não chegou a ser registado	Reporte
`EXERCISE_CLOSED`	A contabilidade do condomínio está fechada no mês da data do documento	Na aplicação, pelo cliente
`EXPENSE_NOT_CREATED`	A despesa não chegou a ser registada	Reporte
`PROPOSAL_NOT_CREATED`	A proposta não chegou a ser submetida	Reporte
`EMAIL_NOT_QUEUED`	A mensagem não foi aceite para envio	Reporte

Os quatro primeiros dependem de configuração do cliente e não se resolvem repetindo. Apresente-os ao utilizador como o que são: falta configurar algo na aplicação.

Sistema indisponível — `502`

UPSTREAM_UNAVAILABLE — nas empresas cujas ocorrências são geridas noutro sistema, esse sistema não respondeu.

Repare que a resposta é um erro e não uma lista vazia: uma lista vazia leria-se como "esta empresa não tem ocorrências", o que seria falso. Repita daqui a pouco, com espera crescente.

Erros ​

Estados HTTP ​

Pedido inválido — 400 ​

Não encontrado — 404 ​

Conflito — 409 ​

Não foi possível concluir — 422 ​