Skip to content
RemindCash

Error handling

The error format, every status code the API returns and how to use request IDs.

Public API status

The v1 API described here is implemented and tested, but api.remindcash.com is not yet open to the public. It opens after final acceptance testing; until then requests return 503. Examples use placeholders — never paste a real key into shared code.

Error format

Every error has the same JSON shape:

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

Validation errors add a fields object with messages per field:

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"
}

Error responses never include stack traces, secrets or other companies' data.

Status codes

Status error.code When
401 unauthenticated Missing, invalid or expired API key.
403 forbidden The key lacks the scope, or the key owner, membership or company is not eligible.
404 not_found The resource does not exist or belongs to another company.
409 conflict Idempotency key reused with a different body, stale expected_version, duplicate external_reference, or a draft-only change on a non-draft receivable.
422 validation_failed A field is missing or invalid, the Idempotency-Key is missing, or a status change is not allowed.
429 rate_limited Too many requests — see Rate limits.
500 server_error Something went wrong on our side. Retry later with the same Idempotency-Key.

Request IDs

Every response carries an X-Request-Id header. Error responses and read responses also include it as request_id in the body. Include it when you contact support so the request can be traced.

Retrying safely

  • Retry 429, 500 and network errors with backoff.
  • For writes, retry with the same Idempotency-Key and the same body; you will get the original result instead of a duplicate.
  • Do not retry 4xx validation or conflict errors unchanged — fix the request first.