Good API clients treat errors as a normal part of life. The key is knowing which errors to retry, which to fix, and which to show to a human.
The error envelope
The SyllHost API always returns errors in one shape, so your code needs only one parser:
{"error": {"code": "insufficient_balance", "message": "Insufficient balance. This order costs $8.00 ..."}}
Use the code in your logic and the message in logs.
Status codes and what to do
| Status | Code example | Retry? | Action |
|---|---|---|---|
| 400 | https_required | No | Use https://. |
| 401 | invalid_api_key | No | Check or replace the key. |
| 402 | insufficient_balance | After top-up | Add funds, then retry with the same Idempotency-Key. |
| 403 | api_not_enabled, ip_not_allowed | No | Ask for access or fix the IP allowlist. |
| 404 | not_found | No | Check the id or name. |
| 409 | conflict | No | Domain unavailable or key reused for a different order. |
| 422 | validation_failed | No | Fix the fields listed in the response. |
| 429 | rate_limited | Yes | Wait for Retry-After seconds. |
| 5xx / timeout | unavailable | Yes | Back off and retry with the same key. |
A simple retry strategy
- Retry only network errors, 429 and 5xx.
- Use exponential backoff: 1s, 2s, 4s, with a small random jitter.
- Cap attempts (for example 3 to 5).
- Always reuse the same Idempotency-Key for the same order.
- Never retry a 4xx error except 402 after a top-up and 429 after waiting.
Do not hide errors from customers
If a hosting order fails, give your customer a clear message and log the code. Insufficient balance should alert you, not your customer.
Log carefully
Log status, code, request path and your own order reference. Never log API keys or passwords returned by the API. See key security.
User-friendly messages
Map API codes to messages your customers understand. "insufficient_balance" becomes "We are processing your order, please wait" while you receive an internal alert. "conflict" for a domain becomes "Sorry, that domain was just taken. Try another." Never show raw API errors to end users; they are written for developers.
Monitoring errors
- Count errors by code per day. A sudden rise in 401 means a key problem, in 402 a funding problem, in 429 an over-eager script.
- Alert on any 5xx streak.
- Log the request path and your own order reference with each error.
Testing your error paths
Most bugs hide in error handling because it rarely runs. Simulate a wrong key, a missing field and a rate limit in your test environment so you know your code reacts correctly before it matters.
FAQ
Does a 402 create anything?
No. When the balance is too low, nothing is created and nothing is charged.
What is a 422?
Your request was understood but invalid, for example a missing required field. The response lists each problem.
Build with our API: read the Reseller API reference and the step-by-step guide. API access is enabled per account, so contact us to request it.