Error Handling

The API returns consistent error responses with an error code and message.

Error Format

{
  "error": {
    "code": "ERR_INVALID_TOKEN",
    "message": "The provided API token is invalid"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Save the request_id when contacting support.

HTTP Status Codes

Status	Description
200	Success
400	Bad request
401	Authentication error
403	Permission denied
404	Not found
422	Validation error
429	Rate limit exceeded
500	Server error

Common Errors

Authentication (401)

{
  "error": {
    "code": "ERR_INVALID_TOKEN",
    "message": "The provided API token is invalid"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Code	Cause
ERR_TOKEN_MISSING	No Authorization header
ERR_INVALID_TOKEN	Token is invalid
ERR_TOKEN_EXPIRED	Token has expired

Authorization (403)

{
  "error": {
    "code": "ERR_FEATURE_NOT_ENABLED",
    "message": "Public API access is not enabled for this account"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Code	Cause
ERR_FORBIDDEN	Insufficient permissions
ERR_FEATURE_NOT_ENABLED	API access not enabled

Not Found (404)

{
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "The requested resource was not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Rate Limit (429)

{
  "error": {
    "code": "ERR_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Check Retry-After header for wait time.

Validation (422)

Validation errors return an array of field-specific errors:

{
  "error": {
    "description": "Validation failed",
    "errors": [
      {
        "field": "page",
        "message": "Must be filled",
        "code": "err_page_must_be_filled"
      },
      {
        "field": "limit",
        "message": "Must be between 1 and 100",
        "code": "err_limit_must_be_between_1_and_100"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Handling Errors

async function fetchData(url, token) {
  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.error.code}: ${error.error.message}`);
  }

  return response.json();
}

Retry Logic

Retry on 429 (rate limit) and 5xx (server) errors:

async function fetchWithRetry(url, token, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${token}` }
    });

    if (response.status === 429) {
      const wait = response.headers.get('retry-after') || 60;
      await new Promise(r => setTimeout(r, wait * 1000));
      continue;
    }

    if (response.status >= 500 && i < retries - 1) {
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
      continue;
    }

    return response;
  }
}