MkSaaS文档Error codes
401 / 402 / 400 / 429 / 5xx — what they mean and how to fix
All errors come back as JSON with a stable shape:
{
"error": {
"code": "insufficient_credits",
"message": "Account has 12 credits, requested job needs 50",
"type": "billing"
}
}HTTP status table
| Status | Meaning | What to do |
|---|---|---|
400 | Bad request — invalid model id or missing parameter | Check error.message, fix payload |
401 | Missing or invalid Authorization header | Verify the rlay_sk_... token, regenerate if leaked |
402 | Insufficient credits | Top up at /dashboard/billing |
403 | Key revoked or account suspended | Contact support |
404 | Job not found, or wrong account ownership | Confirm jobId belongs to this key |
429 | Rate limit exceeded | Back off — see header Retry-After |
5xx | Upstream provider error or routing failure | Retry with exponential backoff; we auto-failover internally |
Error codes you'll actually see
Best practices
- Always inspect
error.codeprogrammatically —error.messagemay change. - Treat 5xx as retryable, 4xx as not (except 429).
- For async jobs, a
failedstatus comes back viaGET /v1/jobs/{id}— you won't get an HTTP 5xx for that path.