Skip to main content
Tender uses conventional HTTP status codes. Codes in the 2xx range mean the request succeeded. Codes in the 4xx range mean the request failed because of something in the request (a missing field, bad credentials, a resource that doesn’t exist). Codes in the 5xx range mean something went wrong on Tender’s side or with an upstream provider.

​
Response envelope

Every response, success or error, uses the same envelope. Success:
data is an object, an array or null, depending on the endpoint.

​
Error envelope

  • status is always "error".
  • message describes the failure. For authentication errors it is a code such as NOT_ALLOWED or INVALID_REQUEST_SIGNATURE (see Authentication).
  • data is usually {} or null. Some endpoints put extra context in it, for example {"txId": "…", "status": "completed"} when a payment can no longer be cancelled.
Always branch on the HTTP status code first, then on message if you need detail. Don’t parse message text for control flow except where an endpoint page documents a specific message.

​
HTTP status codes

The API does not return 422. Validation errors are always 400.

​
Validation errors

Request bodies, query strings and path parameters are validated before the request is processed.
  • A validation failure returns HTTP 400.
  • Only the first failing rule is reported, as a plain string in message:
  • Unknown body fields are silently ignored. They are removed before processing and do not cause an error, so a misspelt optional field is simply dropped. Check field names against the endpoint page.
  • Values are converted to the documented type where possible (for example, "10" to 10 for a numeric field).

​
String input rules

All string values in bodies, query strings and path parameters are cleaned before validation:
  • leading and trailing whitespace is trimmed;
  • HTML tags, javascript: and inline event-handler patterns such as onload= are removed;
  • object keys that start with $ or contain . are dropped.
The agent, conversion, payout, onramp and subwallet endpoints apply stricter rules to most free-text fields: they may not contain the characters $ \ ( ) < >, and are limited to 500 characters unless the endpoint page states another limit. A field that breaks these rules fails validation with a 400.

​
Working with errors

When you receive a 400:
  • Check that the body matches the documented schema (field names, types and required fields).
  • Check path parameters such as {id} or {reference}; a malformed ID returns "Invalid resource ID format".
  • Read message: it names the first field that failed.
When you receive a 401 or 403, see Authentication. When you receive a 409 on a payout, see Idempotency. When you receive a 429, wait until the window resets (the RateLimit-Reset header gives the seconds remaining) before retrying. For 500 and 503, retry with exponential backoff. For payouts, retry with the same Idempotency-Key so the payout can’t be created twice. If an error persists with a payload you believe is correct, capture the full response body and contact support@tender.cash.