Skip to content
RobinReturn (opens in a new tab)
Partner API

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.

StatusMeaning
400Invalid JSON — the body could not be parsed. Nothing else returns 400
401Missing, malformed, unknown or revoked API key
403The key lacks the scope the route requires
404Not found — or a case belonging to another company (never revealed)
409The Idempotency-Key is reserved by a request that has not recorded an answer yet — see Idempotency
413Request body over 1 MiB (the two POST routes only)
422Validation 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
429Rate limit exceeded — see Retry-After and retryAfterSeconds
500Internal 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.

codeMeaning
VALIDATIONA 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_KEYinvoiceFileKey is not under your company's prefix
FILE_NOT_FOUNDNo uploaded object found at invoiceFileKey (did the PUT succeed?)
NON_ENGLAND_WALESDebtor company is registered in Scotland or Northern Ireland (not yet supported)
NOT_YET_DUEThe due date is not in the past
STATUTE_BARREDThe due date is more than six years ago (Limitation Act 1980)
INVOICE_DATE_AFTER_DUEThe invoice date is after its due date
DUPLICATEYour company already has a case for this invoice — a live one chasing it, or a DRAFT from an earlier submission. existingReference names it
DEBTOR_UNVERIFIEDThe debtor is not a fully identified party with a service address. Only returned when debtor verification is switched on for your account
INTERNALRobinReturn 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.