Skip to main content

API Error Reference

All API errors follow a consistent JSON format:
{
  "error": {
    "type": "error_type",
    "code": "http_status_code",
    "message": "Human-readable error message"
  }
}

Error Types

HTTP CodeError TypeDescription
400invalid_request_errorRequest body or parameters are malformed
401authentication_errorAPI key is missing, invalid, or expired
402insufficient_balanceAccount balance is insufficient
403permission_errorAccount lacks access rights to the resource
404not_found_errorModel or resource does not exist
405invalid_request_errorWrong HTTP method
429rate_limit_errorToo many requests, please retry later
500+api_errorAn error occurred while processing your request
529overloaded_errorService is temporarily overloaded, please retry later

Error Examples

Authentication Error (401)

{
  "error": {
    "type": "authentication_error",
    "code": "401",
    "message": "Incorrect API key provided. Please visit https://console.pipellm.com/account/api-keys to find your API key."
  }
}

Rate Limit Error (429)

When you exceed rate limits, the response includes your current limits:
{
  "error": {
    "type": "rate_limit_error",
    "code": "429",
    "message": "Rate limit exceeded. Your current limit is 100 requests per minute (approximately 1 requests per second). Please visit https://console.pipellm.com/billing to upgrade your plan for higher limits.",
    "rate_limit": {
      "rpm": 100,
      "qps": 1
    }
  }
}

Insufficient Balance (402)

{
  "error": {
    "type": "insufficient_balance",
    "code": "402",
    "message": "Insufficient balance. Please recharge your account at https://console.pipellm.com/billing."
  }
}

Internal Error (500)

{
  "error": {
    "type": "api_error",
    "code": "500",
    "message": "Internal server error occurred. Our team has been notified and is working on it."
  }
}

Model-Specific Errors

Model Not Found

When you request an invalid model, the API suggests similar models:
{
  "error": {
    "type": "invalid_request_error",
    "code": "400",
    "message": "gpt-5 is not a valid model ID. Did you mean one of these: gpt-4o, gpt-4-turbo; You can view all the models in our documentation: https://docs.pipellm.com"
  }
}

Model Missing in Request

{
  "error": {
    "type": "invalid_request_error",
    "code": "400",
    "message": "The 'model' field is required but was not provided in the request"
  }
}

🤝 Support