Errors and Rate Limiting

The StreamSkill API uses conventional HTTP response 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 failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with StreamSkill’s servers. In case of an error, the API will return an error response with a JSON object containing the following fields (But some errors provide additional fields):

name - A human-readable name of the error.
message - A human-readable message describing the error.
code - Almost always is 0.
status - Status code of the error.
type - Type of error that was returned. (e.g. bad_request_http_exception)

Error codes

Code	Description
`400`	Bad Request - The request was invalid or cannot be served. (e.g., invalid JSON)
`401`	Unauthorized - Unable to authenticate.
`402`	Insufficient Funds - You don’t have enough funds to do the request.
`404`	Not Found - The specified resource could not be found.
`405`	Method Not Allowed - Action is unavailable for this order.
`409`	Purchase Done - Order already completed.
`422`	Validation Error - The request was well-formed but was unable to be followed due to validation errors.
`429`	Too Many Requests - Rate limit exceeded.
`500`	Action failed - Action not performed.

Rate Limits

Rate-limiting errors (429) happen when you are sending too many requests to the API. All API endpoints are rate-limited using a Token Bucket algorithm.

Default Limits

User Type	Burst (max requests)	Refill Rate
Authenticated	30 requests	2 requests/sec
Guest (no token)	5 requests	0.5 requests/sec

This means authenticated users can make up to 30 requests instantly, then 2 additional requests per second as tokens refill.

Response Headers

The API returns the following headers with every response:

Header	Description
`X-Rate-Limit-Limit`	Maximum number of requests (bucket capacity)
`X-Rate-Limit-Remaining`	Requests remaining in current bucket
`X-Rate-Limit-Reset`	Seconds until bucket is fully refilled (back to capacity)

On 429 responses, an additional header is returned:

Header	Description
`Retry-After`	Seconds to wait before the next request will be allowed

Handling Rate Limits

When you receive a 429 response, wait for the number of seconds specified in the Retry-After header before retrying.

Example 429 Response

HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Limit: 30
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 15
Retry-After: 1
Content-Type: application/json; charset=UTF-8

{
    "name": "Too Many Requests",
    "code": 0,
    "message": "Rate limit exceeded.",
    "status": 429,
    "type": "too_many_requests_http_exception"
}

Get Started

API Documentation

Basic

Purchases

Services

Tariffs

Error codes

Rate Limits

Default Limits

Response Headers

Handling Rate Limits

Example 429 Response

​Error codes

​Rate Limits

​Default Limits

​Response Headers

​Handling Rate Limits

​Example 429 Response

Error codes

Rate Limits

Default Limits

Response Headers

Handling Rate Limits

Example 429 Response