Guides

Error Codes

Copy page

The YouVersion Bible API uses standard HTTP status codes to indicate the success or failure of requests. This page documents all possible error responses and how to handle them.

HTTP Status Codes

2xx Success

• 200 OK: Request was successful
• 204 No Content: Request was successful but no data was returned

4xx Client Errors

• 400 Bad Request: Invalid query string parameters or request format
• 401 Unauthorized: Missing or invalid App Key
• 404 Not Found: The requested resource was not found
• 406 Not Acceptable: Invalid Accept header

5xx Server Errors

• 500 Internal Server Error: An unexpected error occurred on the server
• 503 Service Unavailable: The service is temporarily unavailable

Common Error Scenarios

Authentication Errors

Status Code: 401 Unauthorized

Cause: Missing or invalid X-YVP-App-Key header

Example Response:

Code
 
{
  "error": "Unauthorized",
  "message": "Invalid or missing App Key"
}

Solution: Ensure you're including a valid App Key in the X-YVP-App-Key header with every request.

Invalid Parameters

Status Code: 400 Bad Request

Cause: Invalid query parameters or request format

Example Response:

Code
 
{
  "error": "Bad Request",
  "message": "Invalid language_ranges parameter"
}

Common Issues:

• Invalid language_ranges format
• Invalid version_id (must be an integer)
• Invalid book_usfm (must be 3 characters)
• Invalid chapter_number (must be a positive integer)

Resource Not Found

Status Code: 404 Not Found

Cause: The requested resource doesn't exist

Example Response:

Code
 
{
  "error": "Not Found",
  "message": "Bible version not found"
}

Common Scenarios:

• Bible version ID doesn't exist
• Book USFM identifier is invalid
• Chapter number exceeds the book's chapter count
• Verse number exceeds the chapter's verse count

No Content Available

Status Code: 204 No Content

Cause: Request was successful but no data matches the criteria

Example: Requesting Bible versions for a language that has no available translations

Solution: This is not an error - it's a valid response indicating no content is available for the given parameters.

Invalid Accept Header

Status Code: 406 Not Acceptable

Cause: The Accept header specifies an unsupported content type

Example Response:

Code
 
{
  "error": "Not Acceptable",
  "message": "Unsupported content type requested"
}

Solution: Use application/json in your Accept header or omit the header entirely.

Error Handling Examples

JavaScript (Fetch API)

Code
 
async function makeApiRequest(url, appId) {
  try {
    const response = await fetch(url, {
      headers: {
        'X-YVP-App-Key': appId,
        'Accept': 'application/json'
      }
    });

    if (response.status === 204) {
      return null; // No content
    }

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`${response.status}: ${errorData.message || 'Unknown error'}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

// Usage
try {
  const bibles = await makeApiRequest('https://api.youversion.com/v1/bibles', 'YOUR_APP_KEY');
  console.log('Bibles:', bibles);
} catch (error) {
  console.error('Failed to fetch bibles:', error.message);
}

Python (Requests)

Code
 
import requests

def make_api_request(url, api_key):
    headers = {
        'X-YVP-App-Key': api_key,
        'Accept': 'application/json'
    }
    
    try:
        response = requests.get(url, headers=headers)
        
        if response.status_code == 204:
            return None  # No content
        
        response.raise_for_status()  # Raises an exception for 4xx/5xx status codes
        return response.json()
        
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Authentication failed. Check your App Key.")
        elif e.response.status_code == 404:
            print("Resource not found. Check the URL and parameters.")
        elif e.response.status_code == 400:
            print("Bad request. Check your parameters.")
        else:
            print(f"HTTP error occurred: {e}")
        return None
        
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

# Usage
bibles = make_api_request('https://api.youversion.com/v1/bibles', 'YOUR_APP_KEY')
if bibles:
    print('Bibles:', bibles)

cURL

Code
 
# Example with error handling
response=$(curl -s -w "%{http_code}" -H "X-YVP-App-Key: YOUR_APP_KEY" \
  https://api.youversion.com/v1/bibles)

http_code="${response: -3}"
body="${response%???}"

if [ "$http_code" = "200" ]; then
    echo "Success: $body"
elif [ "$http_code" = "401" ]; then
    echo "Authentication failed. Check your App Key."
elif [ "$http_code" = "404" ]; then
    echo "Resource not found."
elif [ "$http_code" = "400" ]; then
    echo "Bad request. Check your parameters."
else
    echo "Error: HTTP $http_code"
    echo "Response: $body"
fi

Rate Limiting

While not explicitly documented in the OpenAPI spec, the API may implement rate limiting. If you encounter rate limiting:

Status Code: 429 Too Many Requests

Response Headers:

• X-RateLimit-Limit: Maximum requests per time window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when the rate limit resets

Example Response:

Code
 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Solution: Implement exponential backoff and respect the rate limit headers.

Best Practices for Error Handling

1. Always check status codes: Don't assume requests will succeed
2. Handle 204 responses: These are successful but return no content
3. Implement retry logic: For transient errors (5xx status codes)
4. Log error details: Include status codes and error messages in logs
5. Provide user-friendly messages: Translate technical errors for end users
6. Validate parameters: Check parameters before making requests
7. Use appropriate timeouts: Don't let requests hang indefinitely

Testing Error Scenarios

You can test error handling by:

1. Invalid App Key: Use a fake App Key to test 401 responses
2. Invalid Bible ID: Use a non-existent Bible ID (e.g., 99999) to test 404 responses
3. Invalid parameters: Use malformed query parameters to test 400 responses
4. Network issues: Disconnect from the internet to test connection errors

Getting Help

If you encounter errors that aren't documented here or need clarification:

1. Check the API Reference for endpoint-specific error information
2. Review the Authentication guide
3. Contact the YouVersion Platform Team for support