Our API uses standard HTTP status codes and consistent error response formats across all endpoints. Each error response includes a status code and a body containing an array of error messages.

​
Error Response Format

All API error responses follow this format: 
{
  "status": 400,
  "body": {
    "errors": ["Detailed error message here"]
  }
}

​
Error Codes

Here’s a comprehensive list of error codes returned by the API:

​
400 Bad Request

  • Problem: The request is invalid or missing required parameters
  • Common causes:
    • Missing required parameters (e.g., “Staker address is required”)
    • Invalid pagination parameters
    • Invalid Ethereum addresses (must match pattern: ^0x[a-fA-F0-9]$)
    • Invalid withdrawal roots (must match pattern: ^0x[a-fA-F0-9]$)
  • Example responses: 
    {
  "status": 400,
  "body": {
    "errors": ["Operator address is required"]
  }
}

    {
  "status": 400,
  "body": {
    "errors": ["Invalid page number", "Invalid limit value"]
  }
}

​
401 Unauthorized

  • Problem: Authentication failed or authentication credentials were not provided
  • Solution: Ensure you’re providing valid authentication credentials
  • Example response: 
    {
  "status": 401,
  "body": {
    "errors": ["Authentication required"]
  }
}

​
403 Forbidden

  • Problem: The request is not allowed, likely due to permission issues
  • Solution: Verify you have the necessary permissions for the requested resource
  • Example response: 
    {
  "status": 403,
  "body": {
    "errors": ["Access forbidden"]
  }
}

​
404 Not Found

  • Problem: The requested resource doesn’t exist
  • Common scenarios:
    • Staker not found
    • Withdrawal not found
    • Operator not found
  • Example response: 
    {
  "status": 404,
  "body": {
    "errors": ["Withdrawal not found"]
  }
}

​
422 Unprocessable Entity

  • Problem: The request was well-formed but contains invalid parameters
  • Example response: 
    {
  "status": 422,
  "body": {
    "errors": ["Invalid parameter format"]
  }
}

​
429 Too Many Requests

  • Problem: Rate limit exceeded
  • Solution: Reduce request frequency or wait before retrying
  • Example response: 
    {
  "status": 429,
  "body": {
    "errors": ["Rate limit exceeded. Please try again later"]
  }
}

​
500 Internal Server Error

  • Problem: Server encountered an unexpected condition
  • Solution: Retry the request; if persists, contact support
  • Example scenarios:
    • Failed to fetch operator stakers
    • Failed to fetch withdrawals
    • Database query errors
  • Example response: 
    {
  "status": 500,
  "body": {
    "errors": ["Failed to fetch staker details: database error"]
  }
}

​
Validation Patterns

​
Address Format

All Ethereum addresses must match the following pattern:
  • Pattern: ^0x[a-fA-F0-9]{40}$
  • Example: 0x09e6eb09213bdd3698bd8afb43ec3cb0ecff683a

​
Withdrawal Root Format

All withdrawal roots must match the following pattern:
  • Pattern: ^0x[a-fA-F0-9]{64}$
  • Example: 0x123...def

​
Pagination Errors

Many endpoints support pagination with page and limit parameters:
  • page: Default is 1
  • limit: Default is 12
  • Invalid pagination parameters will result in a 400 error

​
Best Practices

  1. Always check the status field in the response
  2. Handle error cases appropriately in your application
  3. Implement exponential backoff for 429 and 500 errors
  4. Validate addresses and parameters before sending requests
  5. Include proper error handling for both network and API errors