Documentation 2026-07-29 22:58 UTC to 2026-07-30 23:58 UTC

14| 401 - IP not authorized | **Cause:** Your request IP does not match the configured IP allowlist for your project or organization. <br /> **Solution:** Send the request from the correct IP, or update your [IP allowlist settings](https://platform.openai.com/settings/organization/security/ip-allowlist). |14| 401 - IP not authorized | **Cause:** Your request IP does not match the configured IP allowlist for your project or organization. <br /> **Solution:** Send the request from the correct IP, or update your [IP allowlist settings](https://platform.openai.com/settings/organization/security/ip-allowlist). |

15| 403 - Country, region, or territory not supported | **Cause:** You are accessing the API from an unsupported country, region, or territory. <br /> **Solution:** Please see [this page](https://developers.openai.com/api/docs/supported-countries) for more information. |15| 403 - Country, region, or territory not supported | **Cause:** You are accessing the API from an unsupported country, region, or territory. <br /> **Solution:** Please see [this page](https://developers.openai.com/api/docs/supported-countries) for more information. |

16| 429 - Credit balance exhausted | **Code:** `credit_balance_exhausted` <br /> **Cause:** Your organization has no prepaid credits remaining. <br /> **Solution:** [Add credits](https://platform.openai.com/settings/organization/billing) to continue using the API. |16| 429 - Credit balance exhausted | **Code:** `credit_balance_exhausted` <br /> **Cause:** Your organization has no prepaid credits remaining. <br /> **Solution:** [Add credits](https://platform.openai.com/settings/organization/billing) to continue using the API. |

17| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |17| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests and follow the `Retry-After` header when it's present. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |

18| 429 - Organization spend limit reached | **Code:** `organization_spend_limit_exceeded` <br /> **Cause:** Your organization reached its enforced spend limit. <br /> **Solution:** Increase or remove your [organization spend limit](https://platform.openai.com/settings/organization/limits). |18| 429 - Organization spend limit reached | **Code:** `organization_spend_limit_exceeded` <br /> **Cause:** Your organization reached its enforced spend limit. <br /> **Solution:** Increase or remove your [organization spend limit](https://platform.openai.com/settings/organization/limits). |

19| 429 - Project spend limit reached | **Code:** `project_spend_limit_exceeded` <br /> **Cause:** Your project reached its enforced spend limit. <br /> **Solution:** Increase or remove the spend limit in your [project settings](https://platform.openai.com/settings/). |19| 429 - Project spend limit reached | **Code:** `project_spend_limit_exceeded` <br /> **Cause:** Your project reached its enforced spend limit. <br /> **Solution:** Increase or remove the spend limit in your [project settings](https://platform.openai.com/settings/). |

20| 429 - Organization usage limit reached | **Code:** `organization_usage_limit_exceeded` <br /> **Cause:** Your organization reached its OpenAI-assigned usage limit. <br /> **Solution:** Request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/). |20| 429 - Organization usage limit reached | **Code:** `organization_usage_limit_exceeded` <br /> **Cause:** Your organization reached its OpenAI-assigned usage limit. <br /> **Solution:** Request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/). |

24 24 

25For billing-related errors, inspect `error.code` to identify the specific cause. The broader `error.type` can still be `insufficient_quota`.25For billing-related errors, inspect `error.code` to identify the specific cause. The broader `error.type` can still be `insufficient_quota`.

26 26 

27Retrying billing, spend, or quota errors won't restore API access. Update the relevant credits or limits before sending another request.

28 

27## WebSocket mode errors29## WebSocket mode errors

28 30 

29If you are using [the Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode), you may see these additional errors:31If you are using [the Responses API WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode), you may see these additional errors:

92To resolve this error, please follow these steps:94To resolve this error, please follow these steps:

93 95 

94- Pace your requests and avoid making unnecessary or redundant calls.96- Pace your requests and avoid making unnecessary or redundant calls.

95- If you are using a loop or a script, make sure to implement a backoff mechanism or a retry logic that respects the rate limit and the response headers. You can read more about our rate limiting policy and best practices in our [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).97- If a `Retry-After` header is present, wait at least as long as it specifies before trying again. If it's missing, use exponential backoff with jitter and limit the number of retries. Each official SDK already honors this header for eligible retries. Read more in our [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).

96- If you are sharing your organization with other users, note that limits are applied per organization and not per user. It is worth checking on the usage of the rest of your team as this will contribute to the limit.98- If you are sharing your organization with other users, note that limits are applied per organization and not per user. It is worth checking on the usage of the rest of your team as this will contribute to the limit.

97- If you are using a free or low-tier plan, consider upgrading to a pay-as-you-go plan that offers a higher rate limit. You can compare the restrictions of each plan in our [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).99- If you are using a free or low-tier plan, consider upgrading to a pay-as-you-go plan that offers a higher rate limit. You can compare the restrictions of each plan in our [rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits).

98- Reach out to your organization owner to increase the rate limits on your project100- Reach out to your organization owner to increase the rate limits on your project

151| InternalServerError | **Cause:** Issue on our side. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. |153| InternalServerError | **Cause:** Issue on our side. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. |

152| NotFoundError | **Cause:** Requested resource does not exist. <br /> **Solution:** Ensure you are the correct resource identifier. |154| NotFoundError | **Cause:** Requested resource does not exist. <br /> **Solution:** Ensure you are the correct resource identifier. |

153| PermissionDeniedError | **Cause:** You don't have access to the requested resource. <br /> **Solution:** Ensure you are using the correct API key, organization ID, and resource ID. |155| PermissionDeniedError | **Cause:** You don't have access to the requested resource. <br /> **Solution:** Ensure you are using the correct API key, organization ID, and resource ID. |

154| RateLimitError | **Cause:** You have hit your assigned rate limit. <br /> **Solution:** Pace your requests. Read more in our [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |156| RateLimitError | **Cause:** You have hit your assigned rate limit. <br /> **Solution:** Pace your requests and follow `Retry-After` when it's present. Each official SDK already honors this header for eligible retries. Read more in our [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |

155| UnprocessableEntityError | **Cause:** Unable to process the request despite the format being correct. <br /> **Solution:** Please try the request again. |157| UnprocessableEntityError | **Cause:** Unable to process the request despite the format being correct. <br /> **Solution:** Please try the request again. |

156 158 

157APIConnectionError159APIConnectionError

220 222 

221If you encounter a `RateLimitError`, please try the following steps:223If you encounter a `RateLimitError`, please try the following steps:

222 224 

223- Send fewer tokens or requests or slow down. You may need to reduce the frequency or volume of your requests, batch your tokens, or implement exponential backoff. You can read our [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits) for more details.225- Send fewer tokens or requests or slow down. You may need to reduce the frequency or volume of your requests, batch your tokens, or use exponential backoff when `Retry-After` isn't present. You can read our [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits) for more details.

224- Wait until your rate limit resets (one minute) and retry your request. The error message should give you a sense of your usage rate and permitted usage.226- When `Retry-After` is present, wait at least as long as it specifies before retrying. The official Python library already honors this header for eligible retries.

225- You can also check your API usage statistics from your account dashboard.227- You can also check your API usage statistics from your account dashboard.

226 228 

227### Persistent errors229### Persistent errors

1# Fast mode

2 

3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 

5Fast mode delivers up to 2.5× faster speeds and more consistent latency while keeping pay-as-you-go flexibility. Fast mode is ideal for high-value, user-facing applications with regular traffic where latency is paramount.

6 

7Priority processing was renamed Fast mode on July 30, 2026. We also increased

8 the speed at which Fast mode operates for `gpt-5.6-sol` to make it up to 2.5×

9 faster than Standard processing. You can use either `service_tier: "priority"`

10 or `service_tier: "fast"` in your API requests to access this functionality.

11 

12## Configuring Fast mode

13 

14You can configure requests to the Responses API or Chat Completions API to use Fast mode through either a request parameter or a project setting.

15 

16To opt in to Fast mode for an individual request, set the [`service_tier` parameter](https://platform.openai.com/docs/api-reference/responses/create#responses-create-service_tier) to `fast`. Setting `service_tier` to `priority` provides the same behavior for supported models.

17 

18Create a response with Fast mode

19 

20```bash

21curl https://api.openai.com/v1/responses \

22 -H "Authorization: Bearer $OPENAI_API_KEY" \

23 -H "Content-Type: application/json" \

24 -d '{

25 "model": "gpt-5.6-sol",

26 "input": "What does 'fit check for my napalm era' mean?",

27 "service_tier": "fast"

28 }'

29```

30 

31```javascript

32import OpenAI from "openai";

33 

34const openai = new OpenAI();

35 

36const response = await openai.responses.create({

37 model: "gpt-5.6-sol",

38 input: "What does 'fit check for my napalm era' mean?",

39 service_tier: "priority",

40});

41 

42console.log(response);

43```

44 

45```python

46from openai import OpenAI

47 

48client = OpenAI()

49 

50response = client.responses.create(

51 model="gpt-5.6-sol",

52 input="What does 'fit check for my napalm era' mean?",

53 service_tier="fast",

54)

55print(response)

56```

57 

58 

59To opt in at the project level, open **Settings**, select **General** under **Project**, and change **Project Service Tier** to **Fast**. Requests that don't specify a `service_tier` then default to Fast mode. Requests for the project transition gradually to Fast mode over time.

60 

61The `service_tier` field in the [Responses](https://platform.openai.com/docs/api-reference/responses/object#responses/object-service_tier) or [Chat Completions](https://platform.openai.com/docs/api-reference/chat/object#chat/object-service_tier) response object identifies the tier used to process the request. For GPT-5.6 and earlier models, the response returns `priority` whether the request specifies `priority` or `fast`.

62 

63## Rate limits and ramp rate

64 

65**Baseline limits**

66 

67Fast mode consumption counts toward rate limits the same way as Standard processing. Use your usual retry logic and wait between attempts. For a given model, Standard processing and Fast mode share the same rate limit.

68 

69**Ramp rate limit**

70 

71If your traffic ramps too fast, the system may downgrade some Fast mode requests to standard speeds and charge standard rates. When this happens, the response contains `service_tier: "default"`. The ramp rate limit may apply if you send at least 1 million tokens per minute (TPM) and increase TPM by more than 50% within 15 minutes.

72 

73To avoid triggering the ramp rate limit:

74 

75- Ramp gradually when changing models or snapshots.

76- Use feature flags to shift traffic over hours, not instantly.

77- Avoid running large extract, transform, and load (ETL) or batch jobs in Fast mode.

78 

79## Usage considerations

80 

81- Fast mode charges a per-token premium over Standard processing. See the [pricing page](https://developers.openai.com/api/docs/pricing?latest-pricing=fast) for details and supported models.

82- Cached input discounts still apply to Fast mode requests.

83- Fast mode supports multimodal requests, including image inputs.

84- To view Fast mode requests in the usage dashboard, select the option to group by service tier. For GPT-5.6 and earlier models, these requests appear as `priority` even when you specify `fast`.

85- Long context, fine-tuned models, and embeddings are not supported.

86 

87## Frequently asked questions

88 

89For account and policy information, see the [Fast mode FAQ](https://help.openai.com/en/articles/11647665-priority-processing-faq).

90 

91### Is Fast mode available in all regions?

92 

93Availability depends on the laws and regulations in each jurisdiction. Contact your account director if you have questions about availability in your region.

94 

95### How does Fast mode interact with Scale Tier?

96 

97Scale Tier and Fast mode are separate. Fast mode requests have separate billing and don't count against purchased Scale Tier TPM bundles. Scale Tier spillover traffic doesn't automatically move to Fast mode.

98 

99### How is Fast mode billed?

100 

101Fast mode charges a per-token premium compared with Standard processing. All processing modes count toward your annual Enterprise spend commitment, and eligible cached input tokens receive the same discounts available for Standard processing.

102 

103To review usage, open the usage dashboard, select Responses or Chat Completions, and group by service tier. To review costs, group by line item.

104 

105### Which models and modalities support Fast mode?

106 

107Fast mode supports the multimodal capabilities available with Standard processing, including image inputs. Long context, fine-tuned models, and embeddings aren't supported. Future GPT models may support Fast mode, but support isn't guaranteed for every model.

108 

109### Are ramp rate limits shared across projects or organizations?

110 

111Yes. All your traffic contributes to the same ramp rate limit. If you routinely encounter ramp rate limits, consider purchasing Scale Tier quota.

112 

113### What happens if Fast mode doesn't meet its latency target?

114 

115Contact your account director if you have questions or concerns. Fast mode and Scale Tier receive the same service-level agreement treatment, and eligible Enterprise agreements may provide service credits when those targets aren't met.

116 

117### Is Fast mode compatible with data residency, Zero Data Retention, and a BAA?

118 

119Yes. Fast mode is compatible with data residency, Zero Data Retention, and a Business Associate Agreement (BAA). Existing endpoint, tool, eligibility, and contractual requirements still apply. See the [Your data guide](https://developers.openai.com/api/docs/guides/your-data) for details.

142console.log(response.output_text);142console.log(response.output_text);

143```143```

144 144 

145```go

146package main

147 

148import (

149 "context"

150 "fmt"

151 

152 "github.com/openai/openai-go/v3"

153 "github.com/openai/openai-go/v3/responses"

154)

155 

156func main() {

157 client := openai.NewClient()

158 

159 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

160 Model: "gpt-5.6",

161 Input: responses.ResponseNewParamsInputUnion{

162 OfInputItemList: responses.ResponseInputParam{

163 responses.ResponseInputItemParamOfMessage(

164 responses.ResponseInputMessageContentListParam{

165 responses.ResponseInputContentParamOfInputText(

166 "Analyze the letter and provide a summary of the key points.",

167 ),

168 {

169 OfInputFile: &responses.ResponseInputFileParam{

170 FileURL: openai.String(

171 "https://www.berkshirehathaway.com/letters/2024ltr.pdf",

172 ),

173 },

174 },

175 },

176 responses.EasyInputMessageRoleUser,

177 ),

178 },

179 },

180 })

181 if err != nil {

182 panic(err)

183 }

184 

185 fmt.Println(response.OutputText())

186}

187```

188 

145```python189```python

146from openai import OpenAI190from openai import OpenAI

147 191 

298console.log(response.output_text);342console.log(response.output_text);

299```343```

300 344 

345```go

346package main

347 

348import (

349 "context"

350 "fmt"

351 "os"

352 

353 "github.com/openai/openai-go/v3"

354 "github.com/openai/openai-go/v3/responses"

355)

356 

357func main() {

358 client := openai.NewClient()

359 

360 file, err := os.Open("draconomicon.pdf")

361 if err != nil {

362 panic(err)

363 }

364 defer file.Close()

365 

366 uploadedFile, err := client.Files.New(context.Background(), openai.FileNewParams{

367 File: file,

368 Purpose: openai.FilePurposeUserData,

369 })

370 if err != nil {

371 panic(err)

372 }

373 

374 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

375 Model: "gpt-5.6",

376 Input: responses.ResponseNewParamsInputUnion{

377 OfInputItemList: responses.ResponseInputParam{

378 responses.ResponseInputItemParamOfMessage(

379 responses.ResponseInputMessageContentListParam{

380 {

381 OfInputFile: &responses.ResponseInputFileParam{

382 FileID: openai.String(uploadedFile.ID),

383 },

384 },

385 responses.ResponseInputContentParamOfInputText(

386 "What is the first dragon in the book?",

387 ),

388 },

389 responses.EasyInputMessageRoleUser,

390 ),

391 },

392 },

393 })

394 if err != nil {

395 panic(err)

396 }

397 

398 fmt.Println(response.OutputText())

399}

400```

401 

301```python402```python

302from openai import OpenAI403from openai import OpenAI

303 404 

454console.log(response.output_text);555console.log(response.output_text);

455```556```

456 557 

558```go

559package main

560 

561import (

562 "context"

563 "encoding/base64"

564 "fmt"

565 "os"

566 

567 "github.com/openai/openai-go/v3"

568 "github.com/openai/openai-go/v3/responses"

569)

570 

571func main() {

572 client := openai.NewClient()

573 

574 data, err := os.ReadFile("draconomicon.pdf")

575 if err != nil {

576 panic(err)

577 }

578 fileData := "data:application/pdf;base64," + base64.StdEncoding.EncodeToString(data)

579 

580 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

581 Model: "gpt-5.6",

582 Input: responses.ResponseNewParamsInputUnion{

583 OfInputItemList: responses.ResponseInputParam{

584 responses.ResponseInputItemParamOfMessage(

585 responses.ResponseInputMessageContentListParam{

586 {

587 OfInputFile: &responses.ResponseInputFileParam{

588 Filename: openai.String("draconomicon.pdf"),

589 FileData: openai.String(fileData),

590 },

591 },

592 responses.ResponseInputContentParamOfInputText(

593 "What is the first dragon in the book?",

594 ),

595 },

596 responses.EasyInputMessageRoleUser,

597 ),

598 },

599 },

600 })

601 if err != nil {

602 panic(err)

603 }

604 

605 fmt.Println(response.OutputText())

606}

607```

608 

457```python609```python

458import base64610import base64

459from openai import OpenAI611from openai import OpenAI

541 541 

542### Parallel function calling542### Parallel function calling

543 543 

544Parallel function calling is not possible when using [built-in544On supported models beginning with GPT-5, functions can be called in parallel

545 tools](https://developers.openai.com/api/docs/guides/tools).545 when [built-in tools](https://developers.openai.com/api/docs/guides/tools) are also available. Built-in

546 tools cannot be included in a parallel function-call batch.

546 547 

547The model may choose to call multiple functions in a single turn. You can prevent this by setting `parallel_tool_calls` to `false`, which ensures exactly zero or one tool is called.548The model may choose to call multiple functions in a single turn. You can prevent this by setting `parallel_tool_calls` to `false`, which ensures exactly zero or one tool is called.

548 549 

13- **Generations**: [Generate images](#generate-images) from scratch based on a text prompt13- **Generations**: [Generate images](#generate-images) from scratch based on a text prompt

14- **Edits**: [Modify existing images](#edit-images) using a new prompt, either partially or entirely14- **Edits**: [Modify existing images](#edit-images) using a new prompt, either partially or entirely

15 15 

16The Image API also includes a variations endpoint for models that support it, such as DALL·E 2.

17 

18### Responses API16### Responses API

19 17 

20The [Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create#responses-create-tools) allows you to generate images as part of conversations or multi-step flows. It supports image generation as a [built-in tool](https://developers.openai.com/api/docs/guides/tools?api-mode=responses), and accepts image inputs and outputs within context.18The [Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create#responses-create-tools) allows you to generate images as part of conversations or multi-step flows. It supports image generation as a [built-in tool](https://developers.openai.com/api/docs/guides/tools?api-mode=responses), and accepts image inputs and outputs within context.

168 168 

1691M token context window was introduced with GPT-5.4, making it easier to analyze entire codebases, long document collections, or extended agent trajectories in a single request.1691M token context window was introduced with GPT-5.4, making it easier to analyze entire codebases, long document collections, or extended agent trajectories in a single request.

170 170 

171We have separate standard pricing for requests under 272K and over 272K tokens, available in the [pricing docs](https://developers.openai.com/api/docs/pricing). If you use [priority processing](https://developers.openai.com/api/docs/guides/priority-processing), any prompt above 272K tokens is automatically processed at standard rates.171We have separate standard pricing for requests under 272K and over 272K tokens, available in the [pricing docs](https://developers.openai.com/api/docs/pricing). If you use [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode), any prompt above 272K tokens is automatically processed at standard rates.

172 172 

173Long context pricing stacks with other pricing modifiers such as data residency and batch.173Long context pricing stacks with other pricing modifiers such as data residency and batch.

174 174 

292 292 

293Using GPT-5 models with the Responses API provides improved intelligence because of the API design. The Responses API can pass the previous turn's CoT to the model. This leads to fewer generated reasoning tokens, higher cache hit rates, and less latency. To learn more, see an [in-depth guide](https://developers.openai.com/cookbook/examples/responses_api/reasoning_items) on the benefits of the Responses API.293Using GPT-5 models with the Responses API provides improved intelligence because of the API design. The Responses API can pass the previous turn's CoT to the model. This leads to fewer generated reasoning tokens, higher cache hit rates, and less latency. To learn more, see an [in-depth guide](https://developers.openai.com/cookbook/examples/responses_api/reasoning_items) on the benefits of the Responses API.

294 294 

295When migrating to GPT-5.4 from an older OpenAI model, start by experimenting with reasoning levels and prompting strategies. Based on our testing, we recommend using our [prompt optimizer](https://platform.openai.com/chat/edit?models=gpt-5.4&optimize=true)—which automatically updates your prompts for GPT-5.4 based on our best practices—and following this model-specific guidance:295When migrating to GPT-5.4 from an older OpenAI model, start by experimenting with reasoning levels and prompting strategies. Use the [prompt optimizer](https://platform.openai.com/chat/edit?models=gpt-5.4&optimize=true) to update your prompts for GPT-5.4 based on current best practices, then follow this model-specific guidance:

296 296 

297- **`gpt-5.2`**: `gpt-5.4` with default settings is meant to be a drop-in replacement.297- **`gpt-5.2`**: `gpt-5.4` with default settings is meant to be a drop-in replacement.

298- **o3**: `gpt-5.4` with `medium` or `high` reasoning. Start with `medium` reasoning with prompt tuning, then increase to `high` if you aren't getting the results you want.298- **o3**: `gpt-5.4` with `medium` or `high` reasoning. Start with `medium` reasoning with prompt tuning, then increase to `high` if you aren't getting the results you want.

381- `top_p`381- `top_p`

382- `logprobs`382- `logprobs`

383 383 

384Requests to GPT-5.4 or GPT-5.2 with any other reasoning effort setting, or to older GPT-5 models—for example, `gpt-5`, `gpt-5-mini`, or `gpt-5-nano`—that include these fields will raise an error.384Requests that include these fields will raise an error for GPT-5.4 or GPT-5.2 with any other reasoning effort setting, or for older GPT-5 models such as `gpt-5`, `gpt-5-mini`, or `gpt-5-nano`.

385 385 

386To achieve similar results with reasoning effort set higher, or with another GPT-5 family model, try these alternative parameters:386To achieve similar results with reasoning effort set higher, or with another GPT-5 family model, try these alternative parameters:

387 387 

8 8 

9This guide describes how Prompt Caching works in detail, so that you can optimize your prompts for lower latency and cost.9This guide describes how Prompt Caching works in detail, so that you can optimize your prompts for lower latency and cost.

10 10 

11## Caching behavior changes when migrating to GPT-5.6

12 

13GPT-5.6 models and later model families cache exact prompt prefixes at cache

14breakpoints. By default, the service places an implicit breakpoint at the latest

15user or tool message. Unlike earlier models, it does not automatically fall

16back to the longest matching unmarked prefix before that breakpoint.

17 

18For example, requests might share 4,000 tokens of instructions and other static

19content, followed by changing timestamps, tool-call history, or user input. If

20the implicit breakpoint includes that changing content, the full prefix at the

21breakpoint differs between requests. As a result, `cached_tokens` can be `0`

22even though the requests share thousands of identical tokens, and the service

23can repeatedly write the changing prefix to cache.

24 

25To reuse the shared content, add an explicit `prompt_cache_breakpoint` at the

26end of the stable prefix and set the same `prompt_cache_key` on requests that

27share it. Content after the breakpoint can then change without invalidating the

28cached prefix.

29 

30To avoid cache-write charges for the changing suffix, set

31`prompt_cache_options.mode` to `explicit`. This disables the implicit

32breakpoint, so only your explicit breakpoints are eligible for cache reads and

33writes. On GPT-5.6 models and later model families, cache writes cost 1.25× the

34uncached input token rate, so caching only the reusable prefix can reduce costs.

35 

36See [Prompt cache breakpoints](#prompt-cache-breakpoints) for request examples,

37supported content blocks, and cache policy options.

38 

11## Structuring prompts39## Structuring prompts

12 40 

13Cache hits are only possible for exact prefix matches within a prompt. To realize caching benefits, place static content like instructions and examples at the beginning of your prompt, and put variable content, such as user-specific information, at the end. This also applies to images and tools, which must be identical between requests.41Cache hits are only possible for exact prefix matches within a prompt. To realize caching benefits, place static content like instructions and examples at the beginning of your prompt, and put variable content, such as user-specific information, at the end. This also applies to images and tools, which must be identical between requests.

210console.log(response.output_text);210console.log(response.output_text);

211```211```

212 212 

213```go

214package main

215 

216import (

217 "context"

218 "fmt"

219 

220 "github.com/openai/openai-go/v3"

221 "github.com/openai/openai-go/v3/responses"

222)

223 

224func main() {

225 client := openai.NewClient()

226 

227 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

228 Model: "gpt-5.6",

229 Instructions: openai.String("Talk like a pirate."),

230 Reasoning: responses.ReasoningParam{

231 Effort: responses.ReasoningEffortLow,

232 },

233 Input: responses.ResponseNewParamsInputUnion{

234 OfString: openai.String("Are semicolons optional in JavaScript?"),

235 },

236 })

237 if err != nil {

238 panic(err)

239 }

240 

241 fmt.Println(response.OutputText())

242}

243```

244 

213```python245```python

214from openai import OpenAI246from openai import OpenAI

215 247 

264console.log(response.output_text);296console.log(response.output_text);

265```297```

266 298 

299```go

300package main

301 

302import (

303 "context"

304 "fmt"

305 

306 "github.com/openai/openai-go/v3"

307 "github.com/openai/openai-go/v3/responses"

308)

309 

310func main() {

311 client := openai.NewClient()

312 

313 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

314 Model: "gpt-5.6",

315 Reasoning: responses.ReasoningParam{

316 Effort: responses.ReasoningEffortLow,

317 },

318 Input: responses.ResponseNewParamsInputUnion{

319 OfInputItemList: responses.ResponseInputParam{

320 responses.ResponseInputItemParamOfMessage(

321 "Talk like a pirate.",

322 responses.EasyInputMessageRoleDeveloper,

323 ),

324 responses.ResponseInputItemParamOfMessage(

325 "Are semicolons optional in JavaScript?",

326 responses.EasyInputMessageRoleUser,

327 ),

328 },

329 },

330 })

331 if err != nil {

332 panic(err)

333 }

334 

335 fmt.Println(response.OutputText())

336}

337```

338 

267```python339```python

268from openai import OpenAI340from openai import OpenAI

269 341 

414console.log(response.output_text);486console.log(response.output_text);

415```487```

416 488 

489```go

490package main

491 

492import (

493 "context"

494 "fmt"

495 "os"

496 

497 "github.com/openai/openai-go/v3"

498 "github.com/openai/openai-go/v3/responses"

499)

500 

501func main() {

502 client := openai.NewClient()

503 

504 instructions, err := os.ReadFile("prompt.txt")

505 if err != nil {

506 panic(err)

507 }

508 

509 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

510 Model: "gpt-5.6",

511 Instructions: openai.String(string(instructions)),

512 Input: responses.ResponseNewParamsInputUnion{

513 OfString: openai.String("How would I declare a variable for a last name?"),

514 },

515 })

516 if err != nil {

517 panic(err)

518 }

519 

520 fmt.Println(response.OutputText())

521}

522```

523 

417```python524```python

418from openai import OpenAI525from openai import OpenAI

419 526 

52 52 

53In addition to seeing your rate limit on your [account page](https://platform.openai.com/settings/organization/limits), you can also view important information about your rate limits such as the remaining requests, tokens, and other metadata in the headers of the HTTP response.53In addition to seeing your rate limit on your [account page](https://platform.openai.com/settings/organization/limits), you can also view important information about your rate limits such as the remaining requests, tokens, and other metadata in the headers of the HTTP response.

54 54 

55You can expect to see the following header fields:55Responses can include the following header fields:

56 56 

57| Field | Sample Value | Description |57| Field | Sample Value | Description |

58| ------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------- |58| ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------- |

59| Retry-After | 56 | The minimum number of seconds to wait before retrying a temporary rate-limit error, when present. |

59| x-ratelimit-limit-requests | 60 | The maximum number of requests that are permitted before exhausting the rate limit. |60| x-ratelimit-limit-requests | 60 | The maximum number of requests that are permitted before exhausting the rate limit. |

60| x-ratelimit-limit-tokens | 150000 | The maximum number of tokens that are permitted before exhausting the rate limit. |61| x-ratelimit-limit-tokens | 150000 | The maximum number of tokens that are permitted before exhausting the rate limit. |

61| x-ratelimit-remaining-requests | 59 | The remaining number of requests that are permitted before exhausting the rate limit. |62| x-ratelimit-remaining-requests | 59 | The remaining number of requests that are permitted before exhausting the rate limit. |

66| x-ratelimit-remaining-project-tokens | 57000 | The remaining number of tokens permitted before exhausting the project-scoped token rate limit. |67| x-ratelimit-remaining-project-tokens | 57000 | The remaining number of tokens permitted before exhausting the project-scoped token rate limit. |

67| x-ratelimit-reset-project-tokens | 3s | The time until the project-scoped token rate limit resets to its initial state. |68| x-ratelimit-reset-project-tokens | 3s | The time until the project-scoped token rate limit resets to its initial state. |

68 69 

69Project-token headers may be present when a project-scoped token limit applies.70Project-token headers may be present when a project-scoped token limit applies. `Retry-After` may be present on `429` responses caused by a temporary rate limit. It does not mean that quota, billing, or other errors that require user action can be resolved by retrying.

70 71 

71### Fine-tuning rate limits72### Fine-tuning rate limits

72 73 

90 91 

91#### Retrying with exponential backoff92#### Retrying with exponential backoff

92 93 

93One easy way to avoid rate limit errors is to automatically retry requests with a random exponential backoff. Retrying with exponential backoff means performing a short sleep when a rate limit error is hit, then retrying the unsuccessful request. If the request is still unsuccessful, the sleep length is increased and the process is repeated. This continues until the request is successful or until a maximum number of retries is reached.94When a request exceeds a temporary rate limit, the API returns a `429` error. The response can include a `Retry-After` header that tells you how many seconds to wait before trying again. Treat this value as a minimum: wait at least that long and add a small random delay so multiple clients don't retry at the same time.

95 

96Each [official OpenAI SDK](https://developers.openai.com/api/docs/libraries#install-an-official-sdk) automatically retries eligible rate-limit errors and honors `Retry-After` when it's present. You don't need to parse the header or add another retry loop for standard API calls.

97 

98If you're using your own HTTP client, follow `Retry-After` when the header is present and contains a valid value. If it's missing or invalid, fall back to exponential backoff with jitter. Limit both the number of attempts and the total time spent retrying. If you add application-level retries, account for the retries your SDK already performs. Don't retry quota, billing, or other errors that require you to take action.

99 

100Exponential backoff means waiting briefly after an unsuccessful request, then increasing the delay after each unsuccessful retry. This continues until the request succeeds or reaches a configured retry limit.

101 

94This approach has many benefits:102This approach has many benefits:

95 103 

96- Automatic retries means you can recover from rate limit errors without crashes or missing data104- Automatic retries means you can recover from rate limit errors without crashes or missing data

198console.log(response.output_text);198console.log(response.output_text);

199```199```

200 200 

201```go

202package main

203 

204import (

205 "context"

206 "fmt"

207 

208 "github.com/openai/openai-go/v3"

209 "github.com/openai/openai-go/v3/responses"

210)

211 

212func main() {

213 client := openai.NewClient()

214 

215 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

216 Model: "gpt-5.6",

217 Instructions: openai.String("Talk like a pirate."),

218 Reasoning: responses.ReasoningParam{

219 Effort: responses.ReasoningEffortLow,

220 },

221 Input: responses.ResponseNewParamsInputUnion{

222 OfString: openai.String("Are semicolons optional in JavaScript?"),

223 },

224 })

225 if err != nil {

226 panic(err)

227 }

228 

229 fmt.Println(response.OutputText())

230}

231```

232 

201```python233```python

202from openai import OpenAI234from openai import OpenAI

203 235 

252console.log(response.output_text);284console.log(response.output_text);

253```285```

254 286 

287```go

288package main

289 

290import (

291 "context"

292 "fmt"

293 

294 "github.com/openai/openai-go/v3"

295 "github.com/openai/openai-go/v3/responses"

296)

297 

298func main() {

299 client := openai.NewClient()

300 

301 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

302 Model: "gpt-5.6",

303 Reasoning: responses.ReasoningParam{

304 Effort: responses.ReasoningEffortLow,

305 },

306 Input: responses.ResponseNewParamsInputUnion{

307 OfInputItemList: responses.ResponseInputParam{

308 responses.ResponseInputItemParamOfMessage(

309 "Talk like a pirate.",

310 responses.EasyInputMessageRoleDeveloper,

311 ),

312 responses.ResponseInputItemParamOfMessage(

313 "Are semicolons optional in JavaScript?",

314 responses.EasyInputMessageRoleUser,

315 ),

316 },

317 },

318 })

319 if err != nil {

320 panic(err)

321 }

322 

323 fmt.Println(response.OutputText())

324}

325```

326 

255```python327```python

256from openai import OpenAI328from openai import OpenAI

257 329 

69| `/v1/vector_stores` | No | 30 days | Until deleted | No | No |69| `/v1/vector_stores` | No | 30 days | Until deleted | No | No |

70| `/v1/images/generations` | No | 30 days | None | Yes, see below for limitations | No |70| `/v1/images/generations` | No | 30 days | None | Yes, see below for limitations | No |

71| `/v1/images/edits` | No | 30 days | None | Yes, see below for limitations | No |71| `/v1/images/edits` | No | 30 days | None | Yes, see below for limitations | No |

72| `/v1/images/variations` | No | 30 days | None | Yes, see below for limitations | No |

73| `/v1/embeddings` | No | 30 days | None | Yes | No |72| `/v1/embeddings` | No | 30 days | None | Yes | No |

74| `/v1/audio/transcriptions` | No | None | None | Yes | No |73| `/v1/audio/transcriptions` | No | None | None | Yes | No |

75| `/v1/audio/translations` | No | None | None | Yes | No |74| `/v1/audio/translations` | No | None | None | Yes | No |

111 110 

112#### `/v1/images`111#### `/v1/images`

113 112 

114- Image generation is Zero Data Retention compatible when using `gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini`, not when using `dall-e-3` or `dall-e-2`.113- Image generation is Zero Data Retention compatible when using `gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini`.

115 114 

116#### `/v1/files`115#### `/v1/files`

117 116 

202| `/v1/files` | Files | All listed regions | None | Service-level support | None | — |201| `/v1/files` | Files | All listed regions | None | Service-level support | None | — |

203| `/v1/fine_tuning/jobs` | Fine-tuning | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14` | None | — |202| `/v1/fine_tuning/jobs` | Fine-tuning | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14` | None | — |

204| `/v1/images/edits` | Images | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | None | — |203| `/v1/images/edits` | Images | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | None | — |

205| `/v1/images/generations` | Images | All listed regions | United States, Europe (EEA + Switzerland) | `dall-e-3`, `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | None | — |204| `/v1/images/generations` | Images | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | None | — |

206| `/v1/moderations` | Moderation | All listed regions | United States, Europe (EEA + Switzerland) | `omni-moderation-latest` | None | — |205| `/v1/moderations` | Moderation | All listed regions | United States, Europe (EEA + Switzerland) | `omni-moderation-latest` | None | — |

207| `/v1/realtime` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-4o-realtime-preview-2025-06-03`, `gpt-realtime`, `gpt-realtime-1.5`, `gpt-realtime-mini`, `gpt-realtime-2`, `gpt-realtime-2.1`, `gpt-realtime-2.1-mini` | None | — |206| `/v1/realtime` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-4o-realtime-preview-2025-06-03`, `gpt-realtime`, `gpt-realtime-1.5`, `gpt-realtime-mini`, `gpt-realtime-2`, `gpt-realtime-2.1`, `gpt-realtime-2.1-mini` | None | — |

208| `/v1/realtime/transcription_sessions` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime-whisper` | None | — |207| `/v1/realtime/transcription_sessions` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime-whisper` | None | — |

26- [chatgpt-image-latest](/api/docs/models/chatgpt-image-latest.md): Previous image model used in ChatGPT.26- [chatgpt-image-latest](/api/docs/models/chatgpt-image-latest.md): Previous image model used in ChatGPT.

27- [codex-mini-latest](/api/docs/models/codex-mini-latest.md): Fast reasoning model optimized for the Codex CLI27- [codex-mini-latest](/api/docs/models/codex-mini-latest.md): Fast reasoning model optimized for the Codex CLI

28- [computer-use-preview](/api/docs/models/computer-use-preview.md): Specialized model for computer use tool28- [computer-use-preview](/api/docs/models/computer-use-preview.md): Specialized model for computer use tool

29- [DALL·E 2](/api/docs/models/dall-e-2.md): Our first image generation model

30- [DALL·E 3](/api/docs/models/dall-e-3.md): Previous generation image generation model

31- [davinci-002](/api/docs/models/davinci-002.md): Replacement for the GPT-3 curie and davinci base models29- [davinci-002](/api/docs/models/davinci-002.md): Replacement for the GPT-3 curie and davinci base models

32- [GPT Image 1](/api/docs/models/gpt-image-1.md): Our previous image generation model30- [GPT Image 1](/api/docs/models/gpt-image-1.md): Our previous image generation model

33- [GPT Image 1.5](/api/docs/models/gpt-image-1.5.md): Our previous image generation model31- [GPT Image 1.5](/api/docs/models/gpt-image-1.5.md): Our previous image generation model

35- [GPT Live Transcribe](/api/docs/models/gpt-live-transcribe.md): Low-latency speech-to-text model for realtime transcription33- [GPT Live Transcribe](/api/docs/models/gpt-live-transcribe.md): Low-latency speech-to-text model for realtime transcription

36- [GPT Transcribe](/api/docs/models/gpt-transcribe.md): High-accuracy speech-to-text model for file and Realtime input transcription34- [GPT Transcribe](/api/docs/models/gpt-transcribe.md): High-accuracy speech-to-text model for file and Realtime input transcription

37- [GPT-3.5 Turbo](/api/docs/models/gpt-3.5-turbo.md): Legacy GPT model for cheaper chat and non-chat tasks35- [GPT-3.5 Turbo](/api/docs/models/gpt-3.5-turbo.md): Legacy GPT model for cheaper chat and non-chat tasks

38- [gpt-3.5-turbo-16k-0613](/api/docs/models/gpt-3.5-turbo-16k-0613.md): Legacy GPT model for cheaper chat and non-chat tasks

39- [gpt-3.5-turbo-instruct](/api/docs/models/gpt-3.5-turbo-instruct.md): An older model only compatible with the legacy Completions endpoint

40- [GPT-4](/api/docs/models/gpt-4.md): An older high-intelligence GPT model36- [GPT-4](/api/docs/models/gpt-4.md): An older high-intelligence GPT model

41- [GPT-4 Turbo](/api/docs/models/gpt-4-turbo.md): An older high-intelligence GPT model37- [GPT-4 Turbo](/api/docs/models/gpt-4-turbo.md): An older high-intelligence GPT model

42- [GPT-4 Turbo Preview](/api/docs/models/gpt-4-turbo-preview.md): An older fast GPT model38- [GPT-4 Turbo Preview](/api/docs/models/gpt-4-turbo-preview.md): An older fast GPT model

26- [chatgpt-image-latest](/api/docs/models/chatgpt-image-latest.md): Previous image model used in ChatGPT.26- [chatgpt-image-latest](/api/docs/models/chatgpt-image-latest.md): Previous image model used in ChatGPT.

27- [codex-mini-latest](/api/docs/models/codex-mini-latest.md): Fast reasoning model optimized for the Codex CLI27- [codex-mini-latest](/api/docs/models/codex-mini-latest.md): Fast reasoning model optimized for the Codex CLI

28- [computer-use-preview](/api/docs/models/computer-use-preview.md): Specialized model for computer use tool28- [computer-use-preview](/api/docs/models/computer-use-preview.md): Specialized model for computer use tool

29- [DALL·E 2](/api/docs/models/dall-e-2.md): Our first image generation model

30- [DALL·E 3](/api/docs/models/dall-e-3.md): Previous generation image generation model

31- [davinci-002](/api/docs/models/davinci-002.md): Replacement for the GPT-3 curie and davinci base models29- [davinci-002](/api/docs/models/davinci-002.md): Replacement for the GPT-3 curie and davinci base models

32- [GPT Image 1](/api/docs/models/gpt-image-1.md): Our previous image generation model30- [GPT Image 1](/api/docs/models/gpt-image-1.md): Our previous image generation model

33- [GPT Image 1.5](/api/docs/models/gpt-image-1.5.md): Our previous image generation model31- [GPT Image 1.5](/api/docs/models/gpt-image-1.5.md): Our previous image generation model

35- [GPT Live Transcribe](/api/docs/models/gpt-live-transcribe.md): Low-latency speech-to-text model for realtime transcription33- [GPT Live Transcribe](/api/docs/models/gpt-live-transcribe.md): Low-latency speech-to-text model for realtime transcription

36- [GPT Transcribe](/api/docs/models/gpt-transcribe.md): High-accuracy speech-to-text model for file and Realtime input transcription34- [GPT Transcribe](/api/docs/models/gpt-transcribe.md): High-accuracy speech-to-text model for file and Realtime input transcription

37- [GPT-3.5 Turbo](/api/docs/models/gpt-3.5-turbo.md): Legacy GPT model for cheaper chat and non-chat tasks35- [GPT-3.5 Turbo](/api/docs/models/gpt-3.5-turbo.md): Legacy GPT model for cheaper chat and non-chat tasks

38- [gpt-3.5-turbo-16k-0613](/api/docs/models/gpt-3.5-turbo-16k-0613.md): Legacy GPT model for cheaper chat and non-chat tasks

39- [gpt-3.5-turbo-instruct](/api/docs/models/gpt-3.5-turbo-instruct.md): An older model only compatible with the legacy Completions endpoint

40- [GPT-4](/api/docs/models/gpt-4.md): An older high-intelligence GPT model36- [GPT-4](/api/docs/models/gpt-4.md): An older high-intelligence GPT model

41- [GPT-4 Turbo](/api/docs/models/gpt-4-turbo.md): An older high-intelligence GPT model37- [GPT-4 Turbo](/api/docs/models/gpt-4-turbo.md): An older high-intelligence GPT model

42- [GPT-4 Turbo Preview](/api/docs/models/gpt-4-turbo-preview.md): An older fast GPT model38- [GPT-4 Turbo Preview](/api/docs/models/gpt-4-turbo-preview.md): An older fast GPT model

603console.log(response.output_text);603console.log(response.output_text);

604```604```

605 605 

606```go

607package main

608 

609import (

610 "context"

611 "fmt"

612 

613 "github.com/openai/openai-go/v3"

614 "github.com/openai/openai-go/v3/responses"

615)

616 

617func main() {

618 client := openai.NewClient()

619 

620 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

621 Model: "gpt-5.6",

622 Input: responses.ResponseNewParamsInputUnion{

623 OfInputItemList: responses.ResponseInputParam{

624 responses.ResponseInputItemParamOfMessage(

625 responses.ResponseInputMessageContentListParam{

626 responses.ResponseInputContentParamOfInputText(

627 "Analyze the letter and provide a summary of the key points.",

628 ),

629 {

630 OfInputFile: &responses.ResponseInputFileParam{

631 FileURL: openai.String(

632 "https://www.berkshirehathaway.com/letters/2024ltr.pdf",

633 ),

634 },

635 },

636 },

637 responses.EasyInputMessageRoleUser,

638 ),

639 },

640 },

641 })

642 if err != nil {

643 panic(err)

644 }

645 

646 fmt.Println(response.OutputText())

647}

648```

649 

606```python650```python

607from openai import OpenAI651from openai import OpenAI

608 652 

755console.log(response.output_text);799console.log(response.output_text);

756```800```

757 801 

802```go

803package main

804 

805import (

806 "context"

807 "fmt"

808 "os"

809 

810 "github.com/openai/openai-go/v3"

811 "github.com/openai/openai-go/v3/responses"

812)

813 

814func main() {

815 client := openai.NewClient()

816 

817 file, err := os.Open("draconomicon.pdf")

818 if err != nil {

819 panic(err)

820 }

821 defer file.Close()

822 

823 uploadedFile, err := client.Files.New(context.Background(), openai.FileNewParams{

824 File: file,

825 Purpose: openai.FilePurposeUserData,

826 })

827 if err != nil {

828 panic(err)

829 }

830 

831 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

832 Model: "gpt-5.6",

833 Input: responses.ResponseNewParamsInputUnion{

834 OfInputItemList: responses.ResponseInputParam{

835 responses.ResponseInputItemParamOfMessage(

836 responses.ResponseInputMessageContentListParam{

837 {

838 OfInputFile: &responses.ResponseInputFileParam{

839 FileID: openai.String(uploadedFile.ID),

840 },

841 },

842 responses.ResponseInputContentParamOfInputText(

843 "What is the first dragon in the book?",

844 ),

845 },

846 responses.EasyInputMessageRoleUser,

847 ),

848 },

849 },

850 })

851 if err != nil {

852 panic(err)

853 }

854 

855 fmt.Println(response.OutputText())

856}

857```

858 

758```python859```python

759from openai import OpenAI860from openai import OpenAI

760 861