API Documentation | Pomelo

Our API uses conventional HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with our servers.

HTTP Status Codes

Status Code	Description
200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
429 - Too Many Requests	Too many requests hit the API too quickly. See Rate Limits.
500, 502, 503, 504 - Server Errors	Something went wrong on our end.

Error Response Format

When an error occurs, our API returns a JSON response with the following structure:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'model' parameter is required",
    "code": "parameter_required",
    "param": "model",
    "status": 400
  }
}

Error Fields

Field	Description
type	The type of error: authentication_error, invalid_request_error, api_error, etc.
message	A human-readable message providing details about the error.
code	A machine-readable error code.
param	If the error is parameter-specific, the parameter related to the error.
status	The HTTP status code.

Common Error Codes

Error Code	Description
parameter_required	A required parameter was not provided.
parameter_invalid	A provided parameter is not valid.
invalid_api_key	The API key provided is not valid.
rate_limit_exceeded	You have exceeded your rate limit.
quota_exceeded	You have exceeded your monthly quota.
server_error	An error occurred on our server.

Handling Errors

We recommend implementing proper error handling in your applications to gracefully handle any API errors. Here's an example of how to handle errors when making API requests:

# Python example
import requests

def make_api_request(endpoint, data):
    url = f"https://api.pomeloapi.example.com{endpoint}"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    try:
        response = requests.post(url, headers=headers, json=data)
        
        # Check if the request was successful
        response.raise_for_status()
        
        # Return the JSON response if the request was successful
        return response.json()
    except requests.exceptions.HTTPError as e:
        # Handle HTTP errors (4xx, 5xx)
        if response.status_code == 400:
            error = response.json().get("error", {})
            print(f"Bad request: {error.get('message')} (Code: {error.get('code')})")
        elif response.status_code == 401:
            print("Authentication error: Invalid API key")
        elif response.status_code == 429:
            print("Rate limit exceeded. Please slow down your requests.")
        else:
            print(f"HTTP error occurred: {e}")
    except requests.exceptions.RequestException as e:
        # Handle network-related errors
        print(f"Request error: {e}")
    
    return None

Need Help?