​
Error Codes

​
HTTP Status Codes

CodeMeaningAction
401Unauthorized — invalid or missing API keyCheck your API key
404Resource not foundVerify endpoint URL and request_id
422Validation error — invalid parametersCheck field-level error details in response
429Rate limitedRespect Retry-After header; see limits and quotas

​
422 Validation Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "prompt": ["The prompt field is required."],
    "model": ["The selected model is invalid."]
  }
}

​
429 Rate Limit Response

{
  "message": "Too Many Attempts."
}
Headers included with 429 responses:
HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-Daily-LimitMaximum daily requests
X-RateLimit-Daily-RemainingRemaining daily requests
X-RateLimit-TypeWhich limit was hit: "minute" or "daily"
Retry-AfterSeconds until the limit resets

​
Job Error Codes

These error codes appear in webhook job.failed payloads and in job status responses:
CodeDescription
WORKER_TIMEOUTWorker timed out processing the job
PROCESSING_ERRORError during inference processing
AGE_RESTRICTEDContent flagged as age-restricted
CONTEXT_LENGTH_EXCEEDEDInput exceeds model context length
INVALID_INPUTInvalid input parameters
UNKNOWN_ERRORUnclassified error

​
Error Handling Example

import requests

resp = requests.post(
    "https://api.modelbeam.ai/api/v1/client/txt2img",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    json={"prompt": "test", "model": "Flux1schnell", "width": 768, "height": 768, "steps": 4, "guidance": 1, "seed": -1}
)

if resp.status_code == 401:
    print("Invalid API key")
elif resp.status_code == 422:
    errors = resp.json().get("errors", {})
    for field, messages in errors.items():
        print(f"{field}: {', '.join(messages)}")
elif resp.status_code == 429:
    retry_after = resp.headers.get("Retry-After", 5)
    print(f"Rate limited. Retry after {retry_after} seconds")
elif resp.status_code >= 200 and resp.status_code < 300:
    print("Success:", resp.json())