Saltar para o conteúdo
RemindCash

Tratamento de erros

O formato dos erros, todos os códigos de estado que a API devolve e como usar os IDs de pedido.

Estado da API pública

A API v1 usa chaves bearer da empresa e exige um período de plano ativo. Os endpoints de rascunhos e de comunicação de pagamentos não enviam mensagens a clientes. Os exemplos usam marcadores — nunca cole uma chave real em código partilhado.

Formato dos erros

Todos os erros têm a mesma forma JSON:

JSON
{
    "error": {
        "code": "not_found",
        "message": "Resource not found."
    },
    "request_id": "9fd120d8-f54e-4413-bc52-a860800ff222"
}

Os erros de validação acrescentam um objeto fields com mensagens por campo:

JSON
{
    "error": {
        "code": "validation_failed",
        "message": "Validation failed.",
        "fields": {
            "currency": ["The selected currency is invalid."],
            "due_date": ["The due date field is required."]
        }
    },
    "request_id": "89a24d53-684a-4e1d-b0ee-2f6a5a7cd2c2"
}

As respostas de erro nunca incluem rastreios de pilha, segredos nem dados de outras empresas.

Códigos de estado

Estado error.code Quando
401 unauthenticated Chave de API em falta, inválida ou expirada.
403 forbidden A chave não tem a permissão, ou o titular da chave, a sua associação à empresa ou a empresa não são elegíveis.
404 not_found O recurso não existe ou pertence a outra empresa.
409 conflict Chave de idempotência reutilizada com um corpo diferente, expected_version desatualizado, external_reference duplicado ou uma alteração só permitida em rascunhos numa cobrança que já não é rascunho.
422 validation_failed Um campo está em falta ou é inválido, falta o Idempotency-Key ou uma mudança de estado não é permitida.
429 rate_limited Demasiados pedidos — veja Limites de pedidos.
500 server_error Algo correu mal do nosso lado. Tente mais tarde com o mesmo Idempotency-Key.

IDs de pedido

Cada resposta traz um cabeçalho X-Request-Id. As respostas de erro e de leitura também o incluem no corpo como request_id. Indique-o quando contactar o apoio, para que o pedido possa ser rastreado.

Repetir com segurança

  • Repita os erros 429, 500 e de rede com espera progressiva (backoff).
  • Nas escritas, repita com o mesmo Idempotency-Key e o mesmo corpo; recebe o resultado original em vez de um duplicado.
  • Não repita sem alterações os erros 4xx de validação ou de conflito — corrija primeiro o pedido.