Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.whisul.com/llms.txt

Use this file to discover all available pages before exploring further.

The Whisul API uses standard HTTP status codes to indicate the outcome of every request. Handling errors correctly — especially for asynchronous jobs — ensures your integration stays resilient when things don’t go as expected. This page covers every status code the API returns, explains what each one means, and shows you how to respond.

​
HTTP status code reference

​
POST /generate

Status codeMeaningWhat to do
202Request accepted. Job is queued.Store the job_id and begin polling.
400Invalid input. The request body was malformed or the prompt field was missing or empty.Fix the request body before retrying. Log the response for debugging.
401Unauthorized. Your API key was missing, invalid, or expired.Check that you’re sending Authorization: Bearer YOUR_API_KEY and that the key is valid.
429Rate limit exceeded. You’ve sent too many requests in a short period.Back off and retry after a delay. See rate limit guidance below.

​
GET /jobs/

Status codeMeaningWhat to do
200Request successful. Check the status field in the response body — it may be "running" or "completed".Continue polling if "running". Process the result if "completed".
404Job not found. The job_id does not exist or has expired.Verify you’re using the correct job_id from the POST /generate response.
500Server error. An unexpected error occurred on Whisul’s side.Retry after a short delay. If the error persists, contact support.

​
Handling errors programmatically

​
400 — Invalid input

A 400 response means the API rejected your request before any job was created. Check that:
  • The request body is valid JSON.
  • The prompt field is present and non-empty.
  • The Content-Type: application/json header is set.
400 response body example
{
  "error": "Invalid input",
  "message": "The 'prompt' field is required and must not be empty."
}

​
401 — Unauthorized

Every request to the Whisul API must include your API key in the Authorization header.
Correct header format
Authorization: Bearer YOUR_API_KEY
If you receive a 401, confirm that:
  • You’re not sending the key as a query parameter or in the request body.
  • The API key has not been revoked. Regenerate it in your dashboard if needed.

​
429 — Rate limit exceeded

Exceeding the rate limit will block your requests until the limit resets. Do not retry immediately — this will prolong the block. Always implement exponential backoff when you receive a 429.
When you receive a 429, wait before retrying. A simple backoff strategy:
  1. On first 429: wait 5 seconds, then retry.
  2. On second 429: wait 10 seconds, then retry.
  3. On each subsequent 429: double the wait time, up to a maximum of 60 seconds.
Avoid polling GET /jobs/{job_id} more frequently than once every 5–10 seconds, which helps prevent hitting rate limits during job monitoring.

​
404 — Job not found

A 404 from GET /jobs/{job_id} means the server has no record of that job. The most common causes are:
  • A typo in the job_id.
  • Using a job_id from a different environment or account.
  • The job has expired from the system after an extended period.
Always use the job_id or poll_url returned directly from POST /generate.

​
500 — Server error

A 500 indicates an unexpected failure on Whisul’s infrastructure. These are typically transient. Retry the same request after 10–30 seconds. If 500 errors persist across multiple retries, check the Whisul status page or contact support.

​
Handling failed jobs

A job with "status": "failed" is distinct from an HTTP error response. The HTTP status code will be 200 (the request itself succeeded), but the job inside could not complete.
Failed job response
{
  "status": "failed",
  "prompt": "a relaxing lo-fi hip hop beat",
  "result": null,
  "error": "Generation failed due to an internal error.",
  "started_at": "2026-02-17 15:39:34",
  "finished_at": "2026-02-17 15:41:05"
}
When you detect "status": "failed":
  • Read the error field for a description of what went wrong.
  • Retry by submitting a new POST /generate request — you cannot resume a failed job.
  • Consider adjusting your prompt if the failure may be related to the input.
See the polling guide for the full job lifecycle and all possible status values.