Rate Limits & Errors

Filoxenos uses standard HTTP status codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, 4xx indicate a client error, and 5xx indicate a server error.

Rate Limits

The number of requests you can make to the Filoxenos API is limited based on your subscription tier.

Pro Tier

100 req / min

Business Tier

500 req / min

If you exceed the rate limit, the API will return a 429 Too Many Requests status code. The Retry-After header will indicate how many seconds to wait before retrying.

Error Format

When an error occurs, the response body will contain a structured error object with a machine-readable code and a human-readable message.

Example Error Response

json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Maximum 100 requests per minute."
  }
}

Error Codes Reference

Parameter	Type	Description
`UNAUTHORIZED`	401	Missing or invalid Authorization header.
`INVALID_KEY`	401	API key not found or has been disabled.
`KEY_EXPIRED`	401	API key has expired and needs rotation.
`SUBSCRIPTION_REQUIRED`	403	API access requires a Pro or Business subscription.
`FORBIDDEN`	403	The API key lacks the required scope for this endpoint.
`NOT_FOUND`	404	The requested resource does not exist.
`VALIDATION_ERROR`	400	The request body or parameters failed validation.
`RATE_LIMITED`	429	Rate limit exceeded (100 requests/min on Pro tier).
`INTERNAL_ERROR`	500	Something went wrong on our end. Please contact support.