Common Errors

This page provides errors that are common between all endpoints. Every error response carries a machine-readable code alongside the HTTP status, so you can branch your error handling logic reliably.

Error Response Format

Every error response follows this structure:

Error envelope
JSON
{
  "status": <number>,          // HTTP status code
  "message": "...",            // Human-readable summary
  "errors": {
    "message": "...",          // Same summary, repeated
    "<field>": [               // Present on validation errors (422)
      "validation messages"
    ]
  },
  "code": "E....."             // Machine-readable error code
}

Real examples from the API, a 401 with an invalid access token, and a 422 validation error where errors also contains per-field validation messages:

401, Invalid access token
JSON
{
    "status": 401,
    "message": "Invalid access token",
    "errors": {
        "message": "Invalid access token"
    },
    "code": "E01401"
}

422, Validation error
JSON
{
    "status": 422,
    "message": "apiKey must be a string",
    "errors": {
        "message": "apiKey must be a string",
        "apiKey": [
            "apiKey must be a string",
            "The apiKey must not exceed 255 characters",
            "apiKey should not be empty"
        ]
    },
    "code": "E00402"
}

Common Error Codes

These errors can be returned by any endpoint:

E40000HTTP 400Bad Request

What it means

The request could not be processed, for example the request body or query parameters are malformed.

How to resolve

Check the request against the endpoint’s documentation in the API reference and correct the payload.

E40001HTTP 401Unauthorized Request invalid access token

What it means

The access token in the X-ACCESS-TOKEN header is missing or invalid.

How to resolve

Generate a fresh token pair with POST /auth/generate-tokens using your API key.

E40002HTTP 401Unauthorized Request invalid refresh token

What it means

The refresh token provided to POST /auth/refresh-token is invalid or no longer valid.

How to resolve

Start a new session from scratch with POST /auth/generate-tokens using your API key.

E40003HTTP 498Token has expired

What it means

The access token has expired. This is an expected part of normal operation.

How to resolve

Call POST /auth/refresh-token with your current refresh token to obtain a new access token.

Quick Reference Table

Code	Meaning	HTTP Status
`E40000`	Bad Request	`400`
`E40001`	Unauthorized Request invalid access token	`401`
`E40002`	Unauthorized Request invalid refresh token	`401`
`E40003`	Token has expired	`498`

Endpoint-Specific Errors

In addition to the common errors above, individual endpoints return their own 400, 404, and 422 errors with endpoint-specific codes such as E00401 (invalid API key) or E01403 (token expired on refresh). These follow the same envelope shape and are documented alongside each endpoint in the API reference.

Handling Errors in Code

The recommended pattern is to match on the code field from the response body, not the HTTP status code alone, this gives you precise control over recovery logic:

TypeScript, Error handling
TS
1async function apiFetch(path: string, accessToken: string) {
const res = await fetch(
  `https://YOUR-SUBDOMAIN.api.roxcustody.com/api/integration${path}`,
  { headers: { 'X-ACCESS-TOKEN': accessToken } }
)
6 
if (!res.ok) {
  const body = await res.json()
9 
  switch (body.code) {
    case 'E40003': // Token has expired, refresh and retry
      const newToken = await refreshAccessToken() // POST /auth/refresh-token
      return apiFetch(path, newToken)
    case 'E40001': throw new Error('Invalid access token, re-authenticate')
    case 'E40002': throw new Error('Invalid refresh token, generate a new session')
    case 'E40000': throw new Error(`Bad request: ${body.message}`)
    default: throw new Error(`API error ${body.code}: ${body.message}`)
  }
}
20 
return res.json()
22}

Postman Collection

The Rox Custody Postman collection includes example requests for every endpoint, so you can explore the API, and reproduce any error response, without writing code.

Download RoxCustody-API.postman_collection.json

ℹ

After importing, set your apiKey variable and call POST /auth/generate-tokens first, the returned access token is what every other request expects in its X-ACCESS-TOKEN header.

Still stuck?

If you're encountering an error not listed here or in the endpoint documentation, contact Rox Custody support:

Email: support@roxcustody.com

← Authentication

Review the token model and refresh flow

Webhooks →

Subscribe to real-time event notifications

1	async function apiFetch(path: string, accessToken: string) {
2	const res = await fetch(
3	`https://YOUR-SUBDOMAIN.api.roxcustody.com/api/integration${path}`,
4	{ headers: { 'X-ACCESS-TOKEN': accessToken } }
5	)
6
7	if (!res.ok) {
8	const body = await res.json()
9
10	switch (body.code) {
11	case 'E40003': // Token has expired, refresh and retry
12	const newToken = await refreshAccessToken() // POST /auth/refresh-token
13	return apiFetch(path, newToken)
14	case 'E40001': throw new Error('Invalid access token, re-authenticate')
15	case 'E40002': throw new Error('Invalid refresh token, generate a new session')
16	case 'E40000': throw new Error(`Bad request: ${body.message}`)
17	default: throw new Error(`API error ${body.code}: ${body.message}`)
18	}
19	}
20
21	return res.json()
22	}