Diagnosing OpenAI API Failures in JSON Schema Extraction
A practical workflow for troubleshooting OpenAI authentication, rate limits, timeouts, and invalid JSON in structured extraction pipelines.
Summary · TL;DR
When structured extraction fails, separate transport and API errors from output-validation failures. Check credentials and project access first, retry only transient errors, and validate the returned JSON against your schema before using it.
Key Takeaways
- A 401 points to credentials, organization membership, or IP allowlisting—not an output-schema problem.
- For 429 responses, inspect the error code: rate limits may call for paced retries, while exhausted credits or spend limits require an account change.
- A successful API response can still contain unusable extraction output; parse and validate it against your JSON Schema.
- Set retry limits and preserve enough request metadata to diagnose repeated failures without logging secrets or sensitive source text.
On this page (7)
Start by separating API failures from extraction failures
A structured extraction pipeline has two distinct failure boundaries: the request may fail before the model returns a usable response, or the response may arrive but fail your parsing or schema checks. Treat them separately. Retrying malformed output without examining the schema or response can waste requests; repeatedly retrying an exhausted credit balance will not restore access.
The OpenAI error-code guide describes API status codes and the corresponding Python library exception types. Its practical distinction is especially useful for extraction workflows: authentication and request errors need configuration fixes, transient throttling or service errors may merit bounded retries, and schema validation belongs in your application after a response arrives. OpenAI API error codes
Check authentication before changing extraction code
For a 401, verify that the application is using the intended active API key and the correct organization context. The error guide also identifies organization membership and IP allowlisting as possible causes. If requests work from one environment but fail from another, compare the outbound IP and the credentials available to each environment before editing the extraction prompt.
For 403, check whether the request is coming from a supported country, region, or territory. A permission or access restriction will not be fixed by changing JSON Schema fields.
Keep credentials out of source control and logs. When debugging, record the environment name and a redacted key identifier—not the secret itself.
Classify 429 responses before retrying
A 429 does not always mean “send the same request again later.” Read the error code and message:
- Request-rate limit: reduce concurrency or pace requests. Honor
Retry-Afterwhen present, and increase traffic gradually rather than immediately returning to the previous rate. - Credit balance exhausted: add credits before resuming requests.
- Organization or project spend limit: review the applicable spend limit.
- Organization usage limit: request an increased approved limit or contact support.
The guide notes that these billing or usage-limit errors do not become recoverable through retries. Build your handler around the specific error code, not just the broad error type: some billing errors can share a broad quota-related type with other failures.
For extraction batches, a simple concurrency cap is often safer than launching every document at once. Retry only requests that are plausibly transient, with a maximum attempt count and backoff. Do not retry validation failures as if they were rate limits.
Handle timeouts and temporary service errors safely
A client timeout means the client did not receive a response in time; it does not prove the request was never processed. For an extraction job, give each source document a stable job identifier and make result persistence idempotent. If you retry, avoid creating duplicate downstream records.
The OpenAI guide identifies 500 server errors and 503 model overload as cases where a retry after a brief wait may help; follow Retry-After when present. It also lists Python library exceptions such as APITimeoutError, InternalServerError, and RateLimitError. A connection failure may instead reflect network, proxy, certificate, or firewall configuration. These cases should not all trigger identical retry behavior.
Illustrative Python pattern: parse, validate, then use
The example below demonstrates the checks around a structured response. It is illustrative, not a tested configuration. Confirm that the model, SDK version, endpoint, and structured-output parameters you use support this request format. The OpenAI error-code guide does not document JSON Schema parameter compatibility.
import json
from jsonschema import validate, ValidationError
from openai import OpenAI, APIConnectionError, APITimeoutError
from openai import APIStatusError, RateLimitError
client = OpenAI()
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"currency": {"type": "string"}
},
"required": ["invoice_number", "total", "currency"],
"additionalProperties": False
}
try:
response = client.responses.create(
model="YOUR_SUPPORTED_MODEL",
input="Extract the invoice number, total, and currency from: ...",
text={
"format": {
"type": "json_schema",
"name": "invoice",
"strict": True,
"schema": schema
}
}
)
data = json.loads(response.output_text)
validate(instance=data, schema=schema)
except (RateLimitError, APITimeoutError, APIConnectionError) as exc:
# Apply a bounded, error-aware retry policy in the job runner.
print(f"Transient or connection failure: {exc}")
except APIStatusError as exc:
# Inspect status and the API error code before deciding what to do.
print(f"API failure: status={exc.status_code}, message={exc}")
except (json.JSONDecodeError, ValidationError) as exc:
# Quarantine the result; do not pass invalid data downstream.
print(f"Response failed JSON parsing or schema validation: {exc}")
If the selected endpoint or model does not support this schema-format parameter, the request may fail as malformed or unsupported. Check the endpoint’s current documentation rather than silently removing validation. Even when constrained output is available, application-side parsing and validation provide a useful boundary before data reaches a database or business process.
A compact diagnosis checklist
- No response or client exception? Check connectivity, timeout settings, proxy, and TLS configuration.
- 401 or 403? Check key, organization access, IP allowlist, and regional availability.
- 429? Inspect the exact code. Pace transient rate-limit failures; resolve credits or limits for account restrictions.
- 500 or 503? Retry within a bounded policy, respecting
Retry-Afterwhen supplied. - Response received but unusable? Capture the response safely, identify whether JSON parsing or schema validation failed, and keep invalid records out of downstream processing.
- Persistent issue? Preserve the model name, error code and message, timestamp and timezone, and relevant request details and headers. Redact API keys and sensitive source content before sharing diagnostics.
Conclusion
For reliable JSON extraction, diagnose the HTTP or SDK error first, then validate successful responses independently. Retry only errors that can plausibly recover, and use the specific error code to distinguish throttling from credits, spend limits, and other access constraints.
FAQ
Should I retry every OpenAI 429 response?
No. Pace and retry request-rate failures within limits, honoring Retry-After when present. Credit exhaustion, spend limits, and usage-limit errors require the relevant account or limit change; retries alone will not restore access.
What should I check for an OpenAI 401 during extraction?
Confirm the API key is correct and active, the request uses the intended organization, and the account belongs to that organization. If an IP allowlist is configured, check that the request originates from an authorized IP.
Does a successful API response guarantee schema-valid JSON?
No. Parse the returned text and validate the resulting object against your application’s JSON Schema before using it. Also confirm that the chosen endpoint, model, and SDK support the structured-output parameters in your request.
What information should I retain when an error persists?
Record the model, error code and message, timestamp and timezone, and relevant request details and headers. Redact credentials and sensitive input before logging or sharing diagnostics.
Related articles
Guides
Grok Imagine Image API Cost Estimate for a JSON Extraction Workflow
Estimate image-generation charges for Grok Imagine Image, identify missing extraction costs, and validate structured records against a JSON schema.
Guides
Qwen4 Max API Cost Guide for JSON Schema Extraction
Estimate Qwen4 Max extraction costs per document and per 100,000 documents, including retries, cache assumptions, and JSON schema validation.
Guides
GPT Image 2 API costs for structured extraction: an assumption-driven estimate
Estimate GPT Image 2 workload costs using explicit token assumptions, and understand why JSON extraction support must be verified before budgeting a production workflow.
Guides
GPT 6.2 Sol API costs for structured extraction: a reproducible estimate
Estimate GPT 6.2 Sol structured extraction costs using explicit token, retry, cache and context-tier assumptions.