Errors

All API errors return a JSON body with an error field. A 4xx response usually requires a request, account, or rate-limit correction; a 5xx response is server-side or temporary, but whether a retry is safe still depends on the action.

Status codes

Code	Name	Meaning
400	Bad Request	Validation failed because a required value is missing, malformed, unsupported, or outside its allowed range. Correct the request before retrying.
403	Forbidden	The key or account is not permitted to perform this action, for example while the account is suspended. Retrying unchanged will not help.
404	Not Found	The requested API resource was not found or is not available to this key. Verify the identifier and account ownership before retrying.
409	Conflict	The request conflicts with existing state, such as reusing an add request_id for a different logical order. Use the original request or a new unique identifier as appropriate.
413	Content Too Large	The request body is too large. Reduce the payload or split supported batch requests before retrying.
429	Too Many Requests	A rate or action limit rejected the request. Inspect X-RateLimit-DeniedBy when present and wait the relative number of seconds in X-RateLimit-Reset.
500	Internal Server Error	An unexpected server-side failure occurred. Do not assume every write is safe to repeat; follow the action-specific retry and reconciliation guidance below.
502	Bad Gateway	The provider rejected the fulfillment request. Review service availability and request data before retrying.
503	Service Unavailable	The API or a required operation is temporarily unavailable, including when no eligible provider was available (provider_not_found). Retry later with backoff, honor Retry-After when present, and preserve the same idempotency identifier where the action supports one.

Example error bodies

Missing required parameter

{
  "error": "Missing required parameter: service"
}

The action requires a parameter that wasn't included. Add it to the request body and retry.

Invalid API key

{
  "error": "Invalid API key"
}

Wrong key, revoked key, or missing key. Check the value matches what's shown in /dashboard/api. The error is identical for missing and invalid to prevent enumeration attacks.

Insufficient balance

{
  "error": "Insufficient balance"
}

Your account balance is below the order's total charge. Top up via /dashboard/wallet, or apply a coupon.

Service not found

{
  "error": "Service not found"
}

The service ID does not exist. Re-fetch the service catalog with action=services and pick a current ID; discontinued services use a separate 400 error.

Rate limit exceeded

{
  "error": "Rate limit exceeded"
}

A rate or action limit rejected the request. Inspect X-RateLimit-DeniedBy when present and wait the relative number of seconds in X-RateLimit-Reset.

Unsupported service-name language

{
  "error": "language must be one of en, es, pt, ru, tr, ar, hi, id, fr, zh",
  "error_code": "INVALID_LANGUAGE"
}

The services and catalog actions accept only en, es, pt, ru, tr, ar, hi, id, fr, or zh. Correct the language value before retrying.

Idempotency & retries

Retry action=add with the same request_id and the same logical request to avoid a duplicate; use a new unique value for a different order. Read actions are safe to repeat. Cancellation retries are safe when the order remains eligible.