Errors
The RobinReturn Partner API error model, HTTP statuses, and the per-case rejection codes returned when creating cases.
Last updated
Error model
Errors return { "error": "<message>" } with the relevant HTTP status. Two statuses add one
field alongside error: 422 also carries issues (the list of validation problems) and 429
also carries retryAfterSeconds. RobinReturn never returns a raw stack trace or internal detail.
Calling a method a route does not expose (only POST on /api/v1/uploads and /api/v1/cases,
only GET on /api/v1/cases/{id}) is handled by the framework and does not use this envelope.
| Status | Meaning |
|---|---|
400 | Invalid JSON — the body could not be parsed. Nothing else returns 400 |
401 | Missing, malformed, unknown or revoked API key |
403 | The key lacks the scope the route requires |
404 | Not found — or a case belonging to another company (never revealed) |
409 | The Idempotency-Key is reserved by a request that has not recorded an answer yet — see Idempotency |
413 | Request body over 1 MiB (the two POST routes only) |
422 | Validation failed — the body did not match the route's schema; issues says what failed. Also returned when an Idempotency-Key is reused with a different body |
429 | Rate limit exceeded — see Retry-After and retryAfterSeconds |
500 | Internal server error |
422 is the status you will hit most often, and it is the one most integrations get wrong: a
field-level problem that breaks the route's own schema — a missing contentLength, a disallowed
contentType, an empty or over-100 cases[], an attestation answer that is not true — is a
422, never a 400, and it rejects the whole request rather than the offending field. An empty
body is also a 422. Branch on 422, not 400, when handling bad input.
Not every bad field is a 422, though: on POST /api/v1/cases a value that clears the route schema
but fails the stricter case-creation rules is returned per case in rejected[] with code
VALIDATION, on an otherwise successful 201/200 — see below.
A 500 on POST /api/v1/cases is rare: a case that fails unexpectedly is reported in
rejected[] with code INTERNAL and the rest of the batch completes. If you do get a 500, do not retry
under the same Idempotency-Key: a 500 records no answer to replay, so that key returns 409 for
up to 24 hours. Resubmit under a new key, or with no key; cases that were already created come back
as DUPLICATE with existingReference rather than being created twice (see
Idempotency).
Per-case rejection codes
POST /api/v1/cases returns a rejected[] array; each entry has an index, the invoiceRef, a
code and a message. These are per case — the request as a whole can still be 201 if other
cases were created. Two codes add a field: DUPLICATE carries existingReference, and
VALIDATION carries issues, a list of { "path", "message" } naming each field that failed.
code | Meaning |
|---|---|
VALIDATION | A field was invalid for case creation; issues names the fields. A common cause is debtorCompanyNo, which must be a 2–10 character alphanumeric company number |
INVALID_FILE_KEY | invoiceFileKey is not under your company's prefix |
FILE_NOT_FOUND | No uploaded object found at invoiceFileKey (did the PUT succeed?) |
NON_ENGLAND_WALES | Debtor company is registered in Scotland or Northern Ireland (not yet supported) |
NOT_YET_DUE | The due date is not in the past |
STATUTE_BARRED | The due date is more than six years ago (Limitation Act 1980) |
INVOICE_DATE_AFTER_DUE | The invoice date is after its due date |
DUPLICATE | Your company already has a case for this invoice — a live one chasing it, or a DRAFT from an earlier submission. existingReference names it |
DEBTOR_UNVERIFIED | The debtor is not a fully identified party with a service address. Only returned when debtor verification is switched on for your account |
INTERNAL | RobinReturn could not confirm whether the case was created. Resubmitting is safe: if it was created, the resubmission is rejected as DUPLICATE |
Handle rejections per case: fix the offending fields and re-send just those. A case rejected as
DUPLICATE because of a draft you do not want is cleared by withdrawing that draft in the
dashboard — see Idempotency.