Reference
Errors
Every error has a fixed code, an HTTP status and a flag that says whether trying again can help. Branch on error_code and retryable, not on the message text.
The error shape
A failed request returns a JSON object with the HTTP status of the error. The error text is a fixed English sentence filled with typed values; it never contains text from other systems.
{
"error": "Minimum quantity is 100",
"error_code": "MINIMUM_QUANTITY",
"retryable": false,
"details": {
"n": 100
}
}Error fields
errorstring- A fixed English message for people. Older scripts that only read
errorkeep working. error_codestring- The error code from the list below. Safe to branch on.
retryablebooleantruewhen sending the same request again later can succeed.detailsobject- The values filled into the message, by name, such as
param,rule,nortime. Present only when there are any. retry_afterinteger- Seconds to wait before trying again. Present when the wait is known, and mirrored in the
Retry-Afterheader.
HTTP statuses
These are the statuses the API uses. HTTP reason phrases are protocol names and stay in English.
- 400
Bad Request
The request is not valid. Fix it before sending it again.
- 401
Unauthorized
The API key is not valid.
- 402
Payment Required
The wallet balance is too low.
- 403
403
The account cannot use the API right now.
- 404
Not Found
The service, order, refill or webhook was not found.
- 405
405
Only POST is accepted.
- 409
Conflict
The request conflicts with the state of a service, an order or an earlier request id.
- 410
410
The service has been discontinued.
- 413
413
The request body is too large.
- 429
Too Many Requests
A rate limit was reached. Wait, then retry.
- 500
500
A fault on our side. Repeating the request is safe.
- 503
503
The API or ordering is paused for a short time. Wait for Retry-After.
Retrying safely
When retryable is true, wait for retry_after or the Retry-After header and add some random jitter, then send the request again. When it is false, change the request first. If a call to add times out or fails with INTERNAL_ERROR, send it again with the same request_id (up to 128 characters): you get the original order back, never a second one.
Examples
key=YOUR_API_KEY&action=add&service=7&link=https://instagram.com/example&quantity=10{
"error": "Minimum quantity is 100",
"error_code": "MINIMUM_QUANTITY",
"retryable": false,
"details": {
"n": 100
}
}key=YOUR_API_KEY&action=add&service=7&link=https://instagram.com/example&quantity=10000{
"error": "Insufficient balance",
"error_code": "INSUFFICIENT_BALANCE",
"retryable": false
}key=YOUR_API_KEY&action=balance{
"error": "Rate limit exceeded",
"error_code": "API_RATE_LIMITED",
"retryable": true,
"retry_after": 12
}key=YOUR_API_KEY&action=add&link=https://instagram.com/example&quantity=100{
"error": "Missing required parameter: service",
"error_code": "MISSING_PARAMETER",
"retryable": false,
"details": {
"param": "service"
}
}All error codes
The message is the fixed template; its placeholders are filled in from details. Each code shows its HTTP status and whether retrying can help.
Request and account
- 401
INVALID_KEY
Invalid API keyThe key is missing, wrong or revoked. Fix the request first.
- 405
METHOD_NOT_ALLOWED
Use POSTThe request was not a POST. Fix the request first.
- 413
BODY_TOO_LARGE
Request body too largeThe request body is too large. Fix the request first.
- 400
INVALID_ACTION
Invalid actionThe action is not one of the documented actions. Fix the request first.
- 400
MISSING_PARAMETER
Missing required parameter: {param}A required parameter is missing. details.param names it. Fix the request first.
- 400
INVALID_PARAMETER
Invalid {param}: {rule}A parameter has an invalid value. details.param and details.rule say which one and why. Fix the request first.
- 400
TOO_MANY_IDS
Maximum 100 IDs per requestA list holds more ids than one request may carry. Fix the request first.
- 403
INACTIVE_ACCOUNT
Account suspendedThe account is suspended. Fix the request first.
- 403
EMAIL_UNVERIFIED
Email verification requiredThe email address of the account is not verified yet. Fix the request first.
Availability and limits
- 503
API_DISABLED
The API is temporarily disabledThe API is switched off for a short time. Retry-After says when to try again. Retrying can help.
- 429
API_RATE_LIMITED
Rate limit exceededA rate limit was reached. See Rate limits. Retrying can help.
- 500
INTERNAL_ERROR
Internal server errorSomething failed on our side. Repeating an add with the same request_id is safe. Retrying can help.
Services and placing orders
- 404
SERVICE_NOT_FOUND
Service not foundNo service has this id, or it is not available to you. Fix the request first.
- 410
SERVICE_DISCONTINUED
Service has been discontinuedThe service has been discontinued. Fix the request first.
- 409
SERVICE_PAUSED
Service is temporarily unavailableThe service is paused for now. Try again later. Retrying can help.
- 503
ORDER_PLACEMENT_PAUSED
Ordering is temporarily pausedOrdering is paused for everyone for a short time. Retry-After says when to try again. Retrying can help.
- 400
INVALID_LINK
Link is invalid for this serviceThe link does not fit this service. Fix the request first.
- 400
LINK_BLOCKED
This link is blocked. Contact support if this is a mistake.The link is blocked. Contact support if you think that is a mistake. Fix the request first.
- 409
LINK_BUSY
An order for this link is still running. Wait until it finishes.An earlier order for this link is still running. Wait until it finishes. Retrying can help.
- 400
MINIMUM_QUANTITY
Minimum quantity is {n}The quantity is below the service minimum. Fix the request first.
- 400
MAXIMUM_QUANTITY
Maximum quantity is {n}The quantity is above the service maximum. Fix the request first.
- 400
QUANTITY_STEP
Quantity must be a multiple of {step}The quantity is not a multiple of the service step. Fix the request first.
- 400
QUANTITY_MISMATCH
quantity must equal the number of items in {param} ({count})The quantity does not match the number of items in a list or reactions field. Fix the request first.
- 400
MINIMUM_ORDER_AMOUNT
Minimum order amount is ${amount}The order is worth less than the minimum order amount. Fix the request first.
- 402
INSUFFICIENT_BALANCE
Insufficient balanceThe wallet balance is lower than the charge. Fix the request first.
- 400
INVALID_OPTION
Invalid {param}: {rule}An extra field has an invalid value. details.param and details.rule say which one and why. Fix the request first.
- 400
OPTION_NOT_SUPPORTED
This service does not accept {param}The service does not take a field you sent. Fix the request first.
- 400
DRIP_FEED_NOT_AVAILABLE
Drip-feed is not available for this serviceThe service has no drip-feed, or none for this quantity. Fix the request first.
- 400
DRIP_FEED_CONFLICT
Send runs and interval, or drip_feed_total_minutes, not bothBoth drip-feed forms were sent in one request. Fix the request first.
- 400
DRIP_FEED_INVALID
{rule}The drip-feed values do not fit the limits. The message says which limit. Fix the request first.
- 429
ORDER_LIMIT_REACHED
Too many orders. Try again later.Too many orders were placed or are open at once. Try again later. Retrying can help.
- 409
SERVICE_CHANGED
Service settings changed while placing the order. Retry.The service settings changed while the order was placed. Send the request again. Retrying can help.
- 409
REQUEST_ID_CONFLICT
request_id was already used with different parametersThis request_id already placed an order with different parameters. Fix the request first.
Orders and cancel
- 404
ORDER_NOT_FOUND
Order not foundNo order with this number belongs to your account. Fix the request first.
- 409
ORDER_FINISHED
Order is already {status}The order has already finished. Fix the request first.
- 409
CANCEL_NOT_AVAILABLE
Cancel is not available for this orderCancel is not possible for this order. Fix the request first.
- 409
CANCEL_REFUSED
The order could not be canceled. You can ask again after {time}.The cancel request was refused. You can ask again after the time in details.time. Retrying can help.
Refills
- 409
REFILL_NOT_AVAILABLE
Refill is not available for this orderRefill is not possible for this order. Fix the request first.
- 409
REFILL_NOT_COMPLETED
Refill is available after the order is completedRefill is possible once the order is completed. Retrying can help.
- 409
REFILL_COOLDOWN
You can request a refill again after {time}A refill was requested for this order recently. Try again after details.time. Retrying can help.
- 409
REFILL_ALREADY_PENDING
A refill request is already in progress for this orderA refill for this order is already in progress. Retrying can help.
- 404
REFILL_NOT_FOUND
Refill not foundNo refill with this id belongs to your account. Fix the request first.
Webhooks
- 409
WEBHOOK_LIMIT
Maximum {limit} webhook endpoints per accountThe account already has the maximum number of webhook endpoints. Fix the request first.
- 404
WEBHOOK_NOT_FOUND
Webhook not foundNo webhook endpoint with this id exists on your account. Fix the request first.
- 400
INVALID_WEBHOOK_URL
Invalid webhook URLThe URL is not a public https address. Fix the request first.