Error Codes - Return Helper API

Every API response uses the standard envelope (correlationId + meta + payload — see Error Handling). When something goes wrong, meta.errorCode is the machine-readable error key. This page lists every value the User and Public APIs can emit.

How to read this page

The Wire HTTP column is the HTTP status the response actually arrives with. The meta.status column is the application-level status inside the body. The meta.errorCode column is the value to branch on in your client code. The meta.error column describes the shape of the per-failure detail. Most error paths in this API return HTTP 200 with the logical status carried in meta.status (the soft-error convention). A small number of cases return real HTTP 400/401/403/409 because they arrive before the API’s own response envelope can be applied or because they represent genuine HTTP semantics.

Validation failures

Almost every write endpoint goes through FluentValidation. Anything caught there — missing required field, value out of range, invalid country code, batch over the limit, business-rule violations expressed as Custom(...) checks — collapses to one error code:

Wire HTTP	`meta.status`	`meta.errorCode`	`meta.error`
`200`	`400`	`VALIDATION_FAILED`	Object keyed by request property name → comma-joined list of error messages. For batch endpoints (e.g. `/api/Recall/createRecallByReturnInventoryId`), entries inside `jobEntryList` are surfaced individually so you can spot which list item failed.

Sample body:

{
  "correlationId": "0HNLB2U6T1QG1:00000001",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "returnInventoryId": "'return Inventory Id' must not be empty."
    }
  }
}

Inspect meta.error — the keys tell you which fields are wrong.

Business-rule and resource errors

These are thrown from business logic when a request is structurally valid but conflicts with the current state of the data, your account, or supporting infrastructure. Each carries a distinct errorCode so you can branch on it.

`meta.errorCode`	Wire HTTP	`meta.status`	When it occurs
`TRACKING_ALREADY_EXIST`	`200`	`400`	A `trackingNumber` you submitted is already used by another active record. Most often hit on Create FBA shipment when the same Amazon tracking number is submitted twice; can also fire on return shipment / resend creates that supply tracking values directly. `meta.error` carries the conflicting record’s identifying data.
`ACCOUNT_IS_BLOCKED`	`200`	`403`	Your API account has been blocked (e.g. for unpaid balance, terms violation). All write endpoints fail until the block is cleared by Return Helper support. `meta.error.message` contains the human-readable reason. Contact `support@returnhelper.com`.
`S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ`	`200`	`404`	An endpoint that needs to fetch a file from S3 (typically VAS file attachments or label artifacts) couldn’t read the object. Check that the file you uploaded earlier still exists and is reachable.
`UPLOAD_FILE_TO_S3_FAIL`	`200`	`500`	An endpoint that needs to upload a file to S3 failed. Transient infrastructure issue — retry with the same idempotency key.
`REQUEST_CUSTOM_DOMAIN_FAIL`	`200`	`500`	A label / branding endpoint that calls out to the custom-domain service failed. Transient — retry.

Auth and access-control failures

These are not soft errors. They arrive with real HTTP status codes because they’re produced before (or outside of) the normal request pipeline.

Wire HTTP	`meta.status`	`meta.errorCode`	When it occurs
`401`	`401`	`null`	`x-rr-apikey` or `x-rr-apitoken` is missing, malformed, or doesn’t match an active account. `meta.error.message` is `"Missing request header"` or similar.
`403`	`403`	`null`	A `RrForbiddenException` was thrown — your account is authenticated but not authorised for the action (e.g. trying to read another tenant’s record). `meta.error.message` is human-readable.

Conflict and not-found

Less common, but reachable:

Wire HTTP	`meta.status`	`meta.errorCode`	When it occurs
`200`	`404`	`null`	A `RrInvalidException` or `RrNotfoundException` — the resource you referenced (by ID) doesn’t exist or doesn’t belong to your account. `meta.error.message` is human-readable.
`409`	`409`	`null`	A `DuplicateTransactionException` — you submitted a state-changing request that the idempotency layer recognised as a duplicate of one already in flight or completed. `meta.error` includes `transactionType`, `headId`, `uniqueChargeKey`, `message`. Treat as a no-op — the original request succeeded.

Idempotency key failures

These apply to write endpoints when you send the x-returnhelper-idempotency-key header. They arrive with real HTTP status codes.

Wire HTTP	`meta.status`	`meta.errorCode`	When it occurs
`400`	`400`	`IDEMPOTENCY_KEY_INVALID`	The key is not 1–128 characters made up of letters, digits, `_`, `.`, `:` or `-`.
`409`	`409`	`IDEMPOTENCY_REQUEST_IN_PROGRESS`	A request with the same key is still running. Retry once it completes.
`409`	`409`	`IDEMPOTENCY_KEY_ALREADY_USED`	A request with the same key already completed inside the validation window. Treat as a no-op — the original request was processed.

A key is scoped to one account plus one HTTP method and route, so the same key value can be reused on a different endpoint without colliding.

Recommended client-side handling

In pseudocode:

response = call(endpoint, body)

if response.status == 401:
  reauth or alert ops
elif response.status == 403:
  surface meta.error.message — account or permission issue
elif response.status == 409:
  treat as success (idempotency replay) — do NOT retry
elif response.status == 200:
  meta = response.body.meta
  if meta.errorCode == 'VALIDATION_FAILED':
    surface meta.error map to the user — field-level messages
  elif meta.errorCode == 'TRACKING_ALREADY_EXIST':
    handle duplicate — likely already created on a previous attempt
  elif meta.errorCode == 'ACCOUNT_IS_BLOCKED':
    halt all calls, alert ops, do not retry
  elif meta.errorCode in ('UPLOAD_FILE_TO_S3_FAIL', 'REQUEST_CUSTOM_DOMAIN_FAIL'):
    retry with the same idempotency key (transient infra)
  elif meta.errorCode == 'S3_OBJECT_NOT_FOUND_OR_NOT_PUBLIC_READ':
    re-upload the source file, then retry
  elif meta.status == 200 and meta.errorCode is null:
    success — read the payload at the top level
  elif meta.status == 404 and meta.errorCode is null:
    resource not found — the ID is wrong or out of scope

correlationId is present on every response. Always log it — it’s how Return Helper support traces a specific request through internal systems.

Where each error code is defined

The error codes documented here come from RrErrorCode constants in the ReturnRequestApiModel.RrException namespace. If you encounter an errorCode value not listed on this page, treat it as an undocumented internal error and report it via support with the correlationId.

​How to read this page

​Validation failures

​Business-rule and resource errors

​Auth and access-control failures

​Conflict and not-found

​Idempotency key failures

​Recommended client-side handling

​Where each error code is defined