Do not treat every Sora 2 failure as one universal "error code." The current evidence splits into several surfaces: OpenAI Platform API status codes, Sora video job states, prompt and policy blocks, ChatGPT or Sora app messages, posting/export failures, and provider-owned wrapper errors. A fix that works for one surface can make another worse.
As rechecked on July 8, 2026, OpenAI's public API error guide documents common API branches such as 401, 403, 429, 500, and 503; the video guide describes Sora generation as an asynchronous POST /v1/videos job with states such as queued, in_progress, completed, and failed; and the deprecations page lists the Videos API plus sora-2 and sora-2-pro for API removal on September 24, 2026. That means a current Sora 2 error guide should help you identify the owner, not preserve a stale table of unsupported numeric folklore.
First Split: Which Surface Failed?
Start by recording the exact wording, screenshot or response body, endpoint, model, project, organization, timestamp, request id if present, and whether the failure happened before create, while queued, during generation, after completion, or during posting/export. Then choose the surface.
| Failure surface | Typical signal | Primary owner | Next move |
|---|---|---|---|
| Direct OpenAI Platform API | HTTP status, JSON error body, headers | OpenAI API request, project, org, model, billing, or status | Read body and headers before retrying |
| Sora video job | queued, in_progress, completed, failed, progress, video id | Videos API job lifecycle | Poll reasonably, use webhook, inspect job error |
| Prompt or policy block | unsafe, content violation, invalid prompt, real person, copyrighted character, face input | Prompt, reference asset, or Sora guardrail | Rewrite the request; do not retry blindly |
| Rate or quota pressure | 429, too many requests, quota, billing, monthly spend | Project/org/model limit or billing state | Separate rate pressure from quota stop |
| ChatGPT or Sora app UI | visible banner, generation button disabled, saved draft, post failure | Consumer app surface | Use app state, account, saved file, and support evidence |
| Wrapper or gateway | provider dashboard error, route id, pool full, upstream unavailable | Provider contract first, upstream second | Compare provider logs with upstream response |
If your visible problem is already narrow, use the narrow owner. The Sora 2 429 guide owns active job queues and rate-limit recovery. The Sora 2 API size-error guide owns size, seconds, and reference-image validation. The Sora 2 invalid prompt guide owns invalid prompt wording beyond generic codes. The Sora 2 content violation guide owns policy-specific refusal wording. Keep this page as the broad router.
Current API Error Reference
OpenAI's API error guide documents these relevant branches for direct Platform API calls. The important detail is not the code alone; it is the owner behind the code.
| API status or wording | What it usually means | What to check first | Retry? |
|---|---|---|---|
| 401 invalid authentication | The API key, org, or authentication context is wrong | API key, selected organization, project, key scope | No, fix auth first |
| 401 incorrect API key | The key is incorrect or no longer active | Current key, environment variable, secret store | No |
| 401 must be a member of an organization | Account is not in the required organization | Organization membership and selected org | No |
| 401 IP not authorized | Project/org IP allowlist rejected the source IP | IP allowlist and deployment egress IP | No |
| 403 unsupported country, region, or territory | API request is from an unsupported location | Official supported-countries page and deployment region | No |
| 429 rate limit reached | Requests are arriving too quickly | Rate-limit headers, Limits page, project, model, queue | Yes, after backoff and throttling |
| 429 exceeded current quota | Credits, monthly spend, billing, or quota is exhausted | Billing, Usage, Limits, spend cap | No, until account state changes |
| 500 server error | OpenAI-side processing issue | Request id, status page, retry after brief wait | Limited retry |
| 503 overloaded | High traffic or service overload | Status page and recent retry pattern | Limited retry |
| 503 Slow Down | Sudden request-rate increase affects reliability | Reduce rate, hold steady, ramp gradually | Only after slowing traffic |
Do not replace this with an old universal Sora table. Current API limits vary by organization, project, model, and usage tier. OpenAI's rate-limit guide also says response headers can expose limit, remaining, and reset values, and that unsuccessful requests can still contribute to per-minute limits. So a tight retry loop can extend the incident.
Sora Video Job States
Sora generation is not a short synchronous request. The official video guide says POST /v1/videos returns a job object with an id and an initial status such as queued or in_progress; you then poll GET /videos/{video_id} or use webhooks until the job finishes. Once the job reaches completed, you fetch the MP4 with GET /videos/{video_id}/content.
Use job state as the next diagnostic layer:
| Job state | Meaning | Practical response |
|---|---|---|
queued | The render is accepted but waiting | Keep the local slot reserved and avoid duplicate creates |
in_progress | The video is being generated | Poll every 10 to 20 seconds or use webhooks |
completed | The render finished | Download and store the asset promptly |
failed | The job ended without a usable video | Inspect the job error and classify owner before retrying |
Video generation can take several minutes depending on model, API load, and resolution. A frontend should not keep submitting new jobs just because a previous job is still waiting. Show queue state, prevent duplicate clicks, and keep one server-side owner for polling. If the repeated symptom is 429 while jobs are still active, hand off to the Sora 2 429 and concurrency guide.
Prompt, Policy, and Guardrail Blocks
For Sora 2 API jobs, OpenAI's video guide lists several content restrictions: the API enforces content suitable for audiences under 18, rejects copyrighted characters and copyrighted music, does not generate real people including public figures, blocks character uploads that depict human likeness by default, and currently rejects input images with human faces.
That means a policy or prompt block is not the same as a transient server error. Retrying the same prompt can waste quota or create repeated refusals. Instead, separate the failure:
| Visible clue | Likely owner | Better next step |
|---|---|---|
| unsafe, content violation, disallowed, or policy wording | Safety boundary | Use the content violation guide |
| invalid prompt, vague rejection, or prompt cannot be processed | Prompt structure or unsupported request | Use the invalid prompt guide |
| real person, public figure, face input, or human likeness reference | Sora guardrail | Remove human-likeness dependency or use an eligible approved route |
| copyrighted character or music | IP boundary | Replace the protected reference with original description |
| image reference mismatch, unsupported file, or wrong target resolution | Input validation | Use the size-error guide |
Do not use prompt obfuscation, bypass wording, or policy-evasion recipes. A current troubleshooting page should help the reader reach a valid request or stop safely, not hide the policy owner.
Rate Limit, Quota, and Billing Errors
429 has two major branches. One branch is traffic pressure: requests are too fast, status polling is too aggressive, or active video jobs are not being queued. That branch can use backoff, random jitter, lower concurrency, and a server-side queue.
The other branch is quota or account state: current quota exceeded, credits exhausted, maximum monthly spend reached, wrong project, wrong organization, or unavailable model. That branch should not be retried until the account state changes.
Use this small decision table:
| Evidence | Action |
|---|---|
| Response says rate limit reached and headers show reset timing | Back off with jitter, pause workers, then resume gradually |
| Response says current quota exceeded or insufficient quota | Stop retries; inspect Billing, Usage, Limits, and spend cap |
| Only video create calls fail while status polling succeeds | Inspect active jobs, size/duration, and video-specific quota |
| Status polling itself fails with 429 | Slow the poller and centralize job state in your backend |
| Multiple app surfaces fail during a status incident | Preserve evidence and wait instead of rotating accounts |
For exact code patterns, use the Sora 2 429 guide or the broader OpenAI API rate-limit guide. This page's job is to route the error correctly.
Access, Authentication, and Permission Errors
Authentication failures should be fixed at the credential and scope layer. Do not regenerate keys, change projects, switch models, and rewrite retry logic in one pass; that makes the evidence unreadable.
For direct API calls, check:
| Layer | What to verify |
|---|---|
| API key | It is the active key used by the running service, not an old local value |
| Organization | The request is sent under the org whose Limits and Billing page you inspected |
| Project | The key belongs to the project that has the model and spend capacity |
| IP allowlist | The deployed service egress IP is allowed if IP restrictions are enabled |
| Region | The request originates from a supported API country, region, or territory |
| Model access | sora-2 or sora-2-pro is actually available to that project before shutdown |
For app UI failures, collect account email, plan surface, region, screenshot, timestamp, and exact wording. Consumer app limits and Platform API limits are not automatically the same contract.
Size, Duration, Reference, and Download Errors
The video guide is explicit about several Sora-specific validation rules. sora-2 and sora-2-pro support 16- and 20-second generations in the current guide. sora-2-pro is the route for 1080p exports in 1920x1080 or 1080x1920. Image references must match the target video size, and supported image input formats are image/jpeg, image/png, and image/webp.
Common validation branches:
| Symptom | Likely branch | Better owner |
|---|---|---|
| size, aspect ratio, or reference image mismatch | Request validation | Sora 2 API size-error guide |
| long render or user repeats submission | Async job lifecycle | This page plus 429/concurrency guide |
| failed after completion when downloading | Asset retrieval or temporary URL | Save final MP4 to your own storage promptly |
| thumbnail or spritesheet confusion | Variant selection | Use variant=thumbnail, variant=spritesheet, or default video route |
| offline shot list fails | Batch request shape | Batch must use JSON and currently supports POST /v1/videos only |
OpenAI's video guide also says generated download URLs are time-limited. If your product needs durable delivery, copy completed assets to your own storage instead of depending on the temporary content URL.
Provider-Owned and Wrapper Errors
A wrapper can be useful, but its error is not automatically an OpenAI Platform error. It may have its own queue, credit ledger, route labels, upstream retry policy, and billing rules. If a provider returns "Sora compatible," "pool full," "rate limited," or "generation failed," record the provider route id and ask whether the request reached OpenAI at all.
Collect:
| Evidence | Why it matters |
|---|---|
| Provider account and route id | Shows which contract owned the request |
| Provider request id | Lets support trace local routing |
| Upstream OpenAI response, if exposed | Separates provider pool issues from OpenAI API issues |
| Billing or credit record | Shows whether the failed job was charged |
| Final asset URL and retention rule | Confirms whether a completed render is retrievable |
Do not promise that a third-party route has lower error rates, higher concurrency, cheaper permanent Sora access, or watermark-free output unless the current provider evidence proves that exact claim. This broad error-code owner should not become a gateway sales page.
The September 24, 2026 Shutdown Boundary
The current OpenAI deprecations page says developers using the Videos API and Sora 2 video generation model aliases and snapshots were notified on March 24, 2026 of API removal on September 24, 2026. The listed entries include the Videos API, sora-2, sora-2-pro, sora-2-2025-10-06, sora-2-2025-12-08, and sora-2-pro-2025-10-06.
So the final branch in any Sora 2 API error list is lifecycle. If a new error appears after a deployment, ask whether the route is approaching shutdown, already removed, or replaced by a different product surface. For existing integrations, keep logs and abstractions clean:
| Migration control | Why it helps |
|---|---|
| Store prompt, model, size, seconds, and reference metadata | Lets you replay or translate jobs later |
| Keep a provider abstraction | Avoids hard-coding product code to a removed API |
| Save completed assets outside temporary download URLs | Preserves user work |
| Tag errors by owner | Shows which failure types block migration first |
| Avoid new long-term Sora-only assumptions | Reduces rework after shutdown |
This is not a reason to panic over every current Sora error. It is a reason not to treat a 2025-style error table as permanent infrastructure.
Support Packet Checklist
If the error survives the first fix, create a clean support packet before changing more variables:
| Include | Exclude |
|---|---|
| Exact error body or screenshot | API keys, bearer tokens, private user data |
| Timestamp with timezone | Unredacted private prompts if not needed |
| Endpoint and model | Random guesses about quotas |
| Project and organization | Claims copied from old blog tables |
| Video id and job status | Multiple unrelated failed experiments mixed together |
| Request id if present | Browser cache theories without evidence |
| OpenAI Status snapshot | Third-party claims without provider logs |
For broad unknown errors, support can act faster when the owner is already narrowed: API status code, video job lifecycle, policy block, rate limit, quota, access, provider, or app UI. A clean packet also prevents your own team from "fixing" the same incident three different ways.
FAQ
Are Sora 2 error codes 1001-1008 official public codes?
Do not assume that. If an app or wrapper shows a numeric local code, capture the exact wording and route it by owner. OpenAI's public API error guide documents common HTTP/API branches such as 401, 403, 429, 500, and 503.
What should I do first after a Sora 2 error?
Identify the surface: direct API, video job state, prompt/policy block, ChatGPT or Sora app UI, posting/export, or provider wrapper. Then collect the error body, timestamp, model, endpoint, project, organization, video id, and request id if present.
Is 429 always a rate-limit error?
No. OpenAI documents a rate-limit branch and a quota/billing branch under 429. Rate pressure can use backoff and queues. Quota or billing needs account repair before retrying.
Why did my Sora job fail after it was accepted?
Sora jobs are asynchronous. A create call can return queued or in_progress, then the job can later reach failed. Inspect the final job error and classify it as prompt, policy, size, quota, status, or provider-owned before retrying.
Can I keep using this page after September 24, 2026?
Use it as a historical triage map only if the Videos API removal has already happened. For current production decisions after that date, check the newest OpenAI video or media-generation docs before applying any Sora 2 API guidance.
Should I switch to a third-party API when errors persist?
Only after you verify the provider's current route, billing, logs, upstream evidence, support path, and shutdown exposure. A provider can own a useful contract, but it does not change OpenAI's official error semantics or lifecycle notices.
Related Sora Error Owners
Use Sora 2 429 and concurrency errors for active jobs, queueing, and rate-limit recovery. Use Sora 2 API size errors for size, seconds, and reference-image problems. Use Sora 2 invalid prompt fixes when the prompt is the owner. Use Sora 2 content violation for safety-policy refusals. Use failed to post Sora 2 when the video exists but publishing, saving, or posting fails.
