Errors

Safe Haven uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Safe Haven's servers (these are rare).

Read the statusCode in the response body

Most endpoints report the outcome in the response body. Always read the statusCode field in the JSON body: a request can return HTTP 200 or 201 with "statusCode": 400 in the body when it fails a business rule (for example insufficient funds or record not found). Request validation errors return HTTP 400. In production their message is generic, so validate your request fields against this reference.

Every response uses this common envelope (responseCode and data are only present on some endpoints):

{
  "statusCode": number,
  "message": string,
  "responseCode"?: string,
  "data"?: object
}

HTTP status codes

Code	When it happens
`200` / `201`	The request was processed. Read `statusCode` in the body: it can still be `400` for a business failure (for example insufficient funds or record not found). POST requests return HTTP 201.
`202` (in the body)	Transfer accepted but not final yet (`"message": "Processing"`). Check Transfer Status or wait for the webhook.
`400`	The request failed validation (a field is missing or has the wrong type). In production the message is generic, so check your fields against this reference.
`403`	Authentication failed. Messages: `Authorization header not found - Access Restricted!`, `Expired token - Access Restricted!`, `Invalid user account - Access Restricted!`, or `Access Restricted: IP not allowed!` (your OAuth app has an IP allowlist and the request came from another IP). Get a new token, or add your server IP to the app.
`404`	The URL or resource doesn't exist.
`429`	Too many requests. The limit is 1500 requests per minute per IP address. Slow down and retry with exponential backoff.
`500`, `502`, `503`	A problem on Safe Haven's side. Retry later; check Transfer Status before retrying a transfer. If it continues, contact support.

Errors from the token endpoint

Exchange Client Credentials (POST /oauth2/token) uses the OAuth error format instead of the envelope above. It returns HTTP 201 with:

{
  "error": "invalid_request",
  "error_description": "Invalid client_assertion. `iat` and `exp` required."
}

Check for an error field before you read access_token.