Error Handling

Learn how to handle errors from the ApiBiblia API.

Error Response Format

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

HTTP Status Codes

Status	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Codes

Authentication Errors

UNAUTHORIZED

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required"
  }
}

Cause: Missing or invalid API key.

Solution: Include a valid API key in the X-API-Key header.

Validation Errors

INVALID_REFERENCE

{
  "success": false,
  "error": {
    "code": "INVALID_REFERENCE",
    "message": "Could not parse Bible reference",
    "details": {
      "reference": "NotABook 1:1"
    }
  }
}

Cause: The reference format is not recognized.

Solution: Use a valid reference format like "John 3:16" or "Juan 3:16".

INVALID_VERSION

{
  "success": false,
  "error": {
    "code": "INVALID_VERSION",
    "message": "Version not found",
    "details": {
      "version": "invalid"
    }
  }
}

Cause: The requested Bible version doesn't exist.

Solution: Use a valid version ID. Check /v1/versions for available versions.

MISSING_PARAMETER

{
  "success": false,
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'ref' is missing"
  }
}

Cause: A required parameter was not provided.

Solution: Include all required parameters in your request.

Resource Errors

NOT_FOUND

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Verse not found",
    "details": {
      "verse_id": "gen_100_1"
    }
  }
}

Cause: The requested resource doesn't exist.

Solution: Verify the resource ID is correct.

Rate Limit Errors

RATE_LIMIT_EXCEEDED

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retry_after": 45
  }
}

Cause: Too many requests in a short period.

Solution: Wait for retry_after seconds before retrying.

Handling Errors

JavaScript Example

async function fetchPassage(ref) {
  const response = await fetch(
    `https://api.apibiblia.com/v1/passage?ref=${encodeURIComponent(ref)}`,
    { headers: { 'X-API-Key': API_KEY } }
  );

  const data = await response.json();

  if (!data.success) {
    switch (data.error.code) {
      case 'UNAUTHORIZED':
        throw new Error('Invalid API key');
      case 'INVALID_REFERENCE':
        throw new Error(`Invalid reference: ${ref}`);
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await sleep(data.error.retry_after * 1000);
        return fetchPassage(ref);
      default:
        throw new Error(data.error.message);
    }
  }

  return data.data;
}

Python Example

import requests

def fetch_passage(ref):
    response = requests.get(
        'https://api.apibiblia.com/v1/passage',
        params={'ref': ref},
        headers={'X-API-Key': API_KEY}
    )

    data = response.json()

    if not data['success']:
        error = data['error']
        if error['code'] == 'RATE_LIMIT_EXCEEDED':
            time.sleep(error.get('retry_after', 60))
            return fetch_passage(ref)
        raise Exception(error['message'])

    return data['data']

Tips

Always Check success

Every response includes a success boolean. Always check it before accessing data.

Log Error Codes

Log error codes for debugging. They're more stable than error messages.