Orbscan Open API errors - Orbscan

Successful responses and documented JSON error bodies use the same three fields: message, status_code, and data.

On success: status_code is "1", message is "OK", and data holds the result.
On error: status_code is "0", message describes the problem, and data is null.

Use the HTTP status code to determine the type of error.

{
  "message": "Missing or invalid API key",
  "status_code": "0",
  "data": null
}

Status codes

HTTP	`message` (example)	Cause & fix
`400`	`Invalid address format` / `Invalid txHash format`	A path or query value is malformed. This covers an `address` that isn’t a valid `0x...` hex address, a `txHash` that isn’t a 32-byte hex hash, and an order book `limit` outside its allowed range.
`401`	`Missing or invalid API key`	The API key is missing or wrong. Check the `Authorization: Bearer` header.
`403`	Varies	The API key is valid but not allowed to use this resource. Check your plan, or contact Orbscan.
`404`	Varies	The API endpoint does not exist. Check the path and spelling. A query that simply finds nothing returns `200` instead, as explained in Empty results are not errors.
`429`	`Rate limit exceeded`	You have sent too many requests. Wait before retrying with exponential backoff. See Rate limits.
`500`	Varies	Something failed on our side. Retry with backoff.
`503`	Varies	A dependent service is temporarily unavailable. For example, order book coverage may have no cached value to return. Retry shortly.

Empty results are not errors

A valid request that finds nothing is not an error. It still succeeds with HTTP 200 and status_code "1". The empty shape depends on the endpoint:

List endpoints (activity, deposits & withdrawals, positions, rewards) return an empty items array:

{
  "message": "OK",
  "status_code": "1",
  "data": { "items": [], "nextCursor": null }
}

Get Actions by Hash returns data: null when the hash is valid but has no indexed action:

{
  "message": "OK",
  "status_code": "1",
  "data": null
}

Get Wallet Address keeps the data object and returns data.walletAddress: null when no mapping exists:

{
  "message": "OK",
  "status_code": "1",
  "data": { "walletAddress": null }
}

Don’t treat these 200 responses as failures. Check the endpoint’s documented data shape to detect an empty result.

Handling errors in code

import requests

resp = requests.get(url, timeout=30)
body = resp.json()

if body["status_code"] != "1":
    raise RuntimeError(f"Orbscan error {resp.status_code}: {body['message']}")

data = body["data"]
empty_list = isinstance(data, dict) and data.get("items") == []
empty_wallet = isinstance(data, dict) and "walletAddress" in data and data["walletAddress"] is None
if data is None or empty_list or empty_wallet:
    print("No results")
else:
    print(data)

const resp = await fetch(url);
const body = await resp.json();

if (body.status_code !== "1") {
  throw new Error(`Orbscan error ${resp.status}: ${body.message}`);
}

const { data } = body;
const emptyList = Array.isArray(data?.items) && data.items.length === 0;
const emptyWallet = data && "walletAddress" in data && data.walletAddress === null;
if (!data || emptyList || emptyWallet) {
  console.log("No results");
} else {
  console.log(data);
}