Skip to main content
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 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 HTTPmeta.statusmeta.errorCodemeta.error
200400VALIDATION_FAILEDObject 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.errorCodeWire HTTPmeta.statusWhen it occurs
TRACKING_ALREADY_EXIST200400A 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_BLOCKED200403Your 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_READ200404An 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_FAIL200500An endpoint that needs to upload a file to S3 failed. Transient infrastructure issue — retry with the same idempotency key.
REQUEST_CUSTOM_DOMAIN_FAIL200500A 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 HTTPmeta.statusmeta.errorCodeWhen it occurs
401401nullx-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.
403403nullA 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 HTTPmeta.statusmeta.errorCodeWhen it occurs
200404nullA 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.
409409nullA 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.
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.