Error Handling Guide

Handle API errors gracefully with consistent patterns across all API4Business endpoints.

Error response format

All API4Business errors follow this structure:

{
  "errorCode": 400,
  "errorType": "proxy",
  "errorMessage": "Invalid Request"
}

Field	Type	Description
errorCode	integer	HTTP status code
errorType	string	Error category (proxy, validation)
errorMessage	string	Human-readable error description

Common error codes

Status	Meaning	When it happens	What to do
400	Bad Request	Invalid input data	Check request format, validate field values
401	Unauthorized	Missing or expired token	Get a new access token
429	Too Many Requests	Rate limit exceeded	Wait and retry with exponential backoff
500	Internal Server Error	Server-side error	Retry after 1-5 seconds
503	Service Unavailable	Upstream service down	Retry with exponential backoff

Recommended error handling pattern

Python

import requests
import time

class Api4BusinessClient:
    def __init__(self, token):
        self.token = token
        self.base_url = "https://api.api4business.com"

    def call(self, method, path, **kwargs):
        url = f"{self.base_url}{path}"
        headers = {
            "Authorization": f"Bearer {self.token}",
            "Content-Type": "application/json"
        }

        for attempt in range(3):
            response = requests.request(method, url, headers=headers, **kwargs)

            if response.status_code == 200:
                data = response.json()
                # Some endpoints return errors as 200
                if "errorCode" in data:
                    raise Exception(f"API error: {data['errorMessage']}")
                return data

            if response.status_code == 401:
                raise Exception("Invalid credentials — refresh your token")

            if response.status_code == 429:
                wait = 2 ** attempt
                time.sleep(wait)
                continue

            if response.status_code >= 500:
                wait = 2 ** attempt
                time.sleep(wait)
                continue

            # 400-level errors — don't retry
            error = response.json()
            raise Exception(f"Error {error['errorCode']}: {error['errorMessage']}")

        raise Exception("Max retries exceeded")

Node.js

class Api4BusinessClient {
  constructor(token) {
    this.token = token;
    this.baseUrl = "https://api.api4business.com";
  }

  async call(method, path, body = null) {
    const options = {
      method,
      headers: {
        "Authorization": `Bearer ${this.token}`,
        "Content-Type": "application/json"
      }
    };
    if (body) options.body = JSON.stringify(body);

    for (let attempt = 0; attempt < 3; attempt++) {
      const response = await fetch(`${this.baseUrl}${path}`, options);

      if (response.status === 200) {
        const data = await response.json();
        if (data.errorCode) throw new Error(`API error: ${data.errorMessage}`);
        return data;
      }

      if (response.status === 401) throw new Error("Invalid credentials");

      if (response.status === 429 || response.status >= 500) {
        await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
        continue;
      }

      const error = await response.json();
      throw new Error(`Error ${error.errorCode}: ${error.errorMessage}`);
    }
    throw new Error("Max retries exceeded");
  }
}

Important: HTTP 200 errors

Bank Verification APIs

The Bank Account Verification APIs may return validation errors with HTTP 200 status. Always check the response body for errorCode or errorMessage fields, even on 200 responses.

// This is a 200 response but contains an error:
{
  "errorCode": 200,
  "errorType": "proxy",
  "errorMessage": "Invalid Account Number"
}

Tracing requests

Every successful response includes an x-request-id header. Log this value for debugging:

response = requests.post(url, headers=headers, json=data)
request_id = response.headers.get("x-request-id")
print(f"Request ID: {request_id}")

Include the x-request-id when contacting support about a specific API call.

Related

• Rate Limits
• Authentication
• Support