Skip to main content
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

​
GET /jobs/

​
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

​
401 — Unauthorized

Every request to the Whisul API must include your API key in the Authorization header.
Correct header format
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
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.