Rate Limiting

To ensure stability for all customers, the API enforces rate limits on specific high-cost actions. Limits are applied per Organization (API Key).

Action	Limit (per minute)	Description
Create Virtual User	100	Creating a new user via the header.
RSS Refresh	30	Force-refreshing an RSS feed.
Media Pull	50	Importing audio from external URLs.
Podcast Import	30	Importing full podcasts via RSS.
General API	1000	All other standard requests.

Handling 429 Responses

If you exceed a limit, the API returns a 429 Too Many Requests status code. The response body will contain:

code: RATE_LIMIT_EXCEEDED
retryAfter: The number of seconds to wait before retrying.


{
  "success": false,
  "error": {
    "errorCode": "RATE_LIMIT_EXCEEDED",
    "errorMessage": "Too many media pull requests. Please slow down.",
    "retryAfter": 12
  }
}

Error Handling

The API uses standard HTTP status codes along with a structured JSON error response.

Common Error Codes

Code	HTTP	Description
`BAD_REQUEST`	400	The request was malformed.
`VALIDATION_ERROR`	400	Input data failed validation (e.g., missing required fields).
`UNAUTHENTICATED`	401	API Key is missing or invalid.
`UNAUTHORIZED`	403	You do not have permission to access this resource.
`NOT_FOUND`	404	The resource (Podcast, Episode, Audio) does not exist.
`INTERNAL_SERVER_ERROR`	500	Something went wrong on our end.

Validation Errors

For VALIDATION_ERROR (400), the response typically includes details about which fields failed:


{
  "message": "Validation Failed",
  "details": {
    "title": "Title is required",
    "ownerEmail": "Invalid email format"
  }
}