Error Handling

💡 Learn how to handle errors when using Billy's API

The Billy API uses conventional HTTP response codes to indicate the success or failure of an API request. This page details how to handle errors effectively and what to expect in error responses.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

• 2xx Success: The request was successful
• 4xx Client Error: The request was invalid or cannot be processed
• 5xx Server Error: An internal server error occurred

Error Summary

Error Response Format

When an error occurs, the API returns a JSON response with a detail property containing a human-readable description of the error:

{
  "detail": "API key required in AUTHORIZATION header, Expected: 'Bearer billy:o:yyyyyyyyyyyyyyyy:xxxxxxxxxxxxxxxxx'"
}

Success Codes

200 OK

The request was successful and the response contains the requested data.

{
  "items": [
    {
      "id": "evt_64f1c2a9e8b4a12f9c0a1234",
      "title": "Electro Night Festival",
      "description": "An immersive electronic music experience with top international DJs."
    }
  ],
  "page": 1,
  "perPage": 10,
  "totalPages": 1
}

204 No Content

The request was successful but there is no content to return. This occurs when requesting a page outside the pagination range.

null

Error Codes

400 Bad Request

The request was malformed or contains invalid parameters.

Missing API Key

{
  "detail": "API key required in AUTHORIZATION header, Expected: 'Bearer billy:o:yyyyyyyyyyyyyyyy:xxxxxxxxxxxxxxxxx'"
}

Invalid API Key Format

{
  "detail": "Invalid API key format. Value: 'xxxxxxxxxxxxxxxS', Expected: 'Bearer billy:o:yyyyyyyyyyyyyyyy:xxxxxxxxxxxxxxxxx'"
}

Invalid Query Parameters

{
  "detail": "Invalid query parameters",
  "errors": [
    {
      "loc": ["query", "page"],
      "msg": "Input should be greater than or equal to 1",
      "type": "greater_than_equal"
    }
  ]
}

Common validation errors include:

• Missing required fields
• Invalid parameter values
• Out-of-range values (e.g., page < 1)
• Malformed request body

403 Forbidden

The request lacks valid authentication credentials or the API key is invalid/revoked.

API Key Not Found

{
  "detail": "Forbidden : API key not found"
}

API Key Revoked

{
  "detail": "Forbidden : API key revoked"
}

429 Too Many Requests

The request rate limit has been exceeded. The API implements rate limiting to ensure fair usage and system stability.

{
  "detail": "Too Many Requests - backpressure applied (Header 'Retry-After' in seconds)"
}

When you receive a 429 response, check the Retry-After header to know how many seconds to wait before retrying the request.

Troubleshooting Guide

"API key required in AUTHORIZATION header"

Cause: The request is missing the Authorization header or it's malformed.

Solution: Ensure your request includes:

Authorization: Bearer billy:o:<organization_id>:<api_key>

"Forbidden : API key not found"

Cause: The API key provided doesn't exist or has been deleted.

Solution:

• Verify the API key in your Billy dashboard
• Ensure you're using the correct environment (sandbox vs. production)
• Check that the organization ID matches your API key

"Forbidden : API key revoked"

Cause: The API key has been revoked and is no longer valid.

Solution: Generate a new API key in your Billy dashboard and update your application.

"Too Many Requests"

Cause: You've exceeded the rate limit for your API key.

Solution:

• Implement retry logic with exponential backoff
• Check the Retry-After header
• Consider caching responses to reduce API calls
• Contact support if you need higher rate limits