Errors
Error envelope, status codes and limits.
Envelope
Billing API errors usually use this envelope. Generation methods also use code, message and data; check the contract of the specific method:
{
"statusCode": 400,
"message": "duration must be an integer number"
}statusCode— the HTTP code;message— a string or an array of strings (validation errors);code— a machine-readable code (not always present).
Codes
| Code | When |
|---|---|
| 400 | Bad request parameters (DTO validation) |
| 401 | No key / key unknown or deactivated |
| 403 | Legacy service key; access denied |
| 404 | Resource not found |
| 429 | Rate limit exceeded. Billing/webhooks default to 60/min per API key, or per partner for sessions. Additional IP limits apply: table. Follow Retry-After when present |
| 500 | Internal error; the outcome of a write may be unknown. Follow the retry rules below |
Validation
The global validation pipeline strips unknown fields and coerces types. The message array lists every violation at once:
{
"statusCode": 400,
"message": [
"duration must be an integer number",
"resolution must be shorter than or equal to 16 characters"
]
}Retry guidance
| Operation | After 429, 5xx or a network timeout |
|---|---|
| Read balance, history or task status | Retry with bounded attempts and exponential backoff; follow Retry-After |
POST /v1/billing/pricing/estimate | An estimate neither starts a task nor reserves funds; a bounded retry is safe |
POST /v1/billing/payment/link | Keep the original Idempotency-Key and amount; do not create a new key to retry the same operation. An amount conflict returns 409 |
| Submit a generation | Do not retry automatically. If you have data.task_id, check that task. A charge or its absence does not prove the provider rejected the request |
| Create an invoice or register a webhook | Check invoice history / endpoint list first; there is no general idempotency guarantee |
| Replay a webhook delivery | Check receiver records and delivery history first. Replay keeps eventId; the receiver must deduplicate events |
For 401/403 fix authentication; retrying with the same invalid key or session will not help. For 400 fix the parameters. Bound polling time and retain the task identifier for later checks.
Unknown submission outcome
If the submission response was lost and no task_id is available, do not send another paid request. Check task history in the cabinet and use Apergrex contacts. Include the UTC time, API path, HTTP status and known identifiers. Never send an API key, cookie, signature or webhook secret.