OpenAI Files API upload failed with HTTP ${response.status}

Error message

OpenAI Files API upload failed with HTTP ${response.status}

What it means

Thrown when the OpenAI Files API responded but with a non-2xx HTTP status. It means the request reached OpenAI and was rejected — the status code (401 invalid key, 403 forbidden, 413 too large, 429 rate limit, 5xx outage) is interpolated into the message. Unlike error 750, the network round-trip succeeded.

Source

Thrown at packages/coding-agent/src/blob-broker/provider-files-openai.ts:101

			form.append(
				"file",
				new Blob([uploadRequest.bytes], { type: uploadRequest.mimeType }),
				fileName(uploadRequest),
			);

			let response: Response;
			try {
				response = await request(OPENAI_FILES_URL, {
					method: "POST",
					headers: { Authorization: authorization },
					body: form,
					signal: uploadRequest.signal,
				});
			} catch {
				throw new Error("OpenAI Files API upload request failed");
			}
			if (!response.ok) {
				throw new Error(`OpenAI Files API upload failed with HTTP ${response.status}`);
			}

			let payload: unknown;
			try {
				payload = await response.json();
			} catch {
				throw new Error("OpenAI Files API returned an invalid upload response");
			}
			const file = parseOpenAIFileResponse(payload);
			if (file.status === "error") throw new Error("OpenAI Files API reported that the upload failed");

			const deleteUrl = `${OPENAI_FILES_URL}/${encodeURIComponent(file.id)}`;
			return {
				provider: "openai",
				id: file.id,
				mimeType: uploadRequest.mimeType,
				bytes: file.bytes,
				delete: {

View on GitHub (pinned to 9690622007)

Solutions

Read the HTTP status in the message: 401/403 → fix the API key and its scopes; 413 → shrink or compress the file; 429 → back off and retry later; 5xx → check status.openai.com
Verify the key is a real OpenAI platform key (not an Azure/OpenRouter key) since this client only targets api.openai.com/v1
Retry only on 429/5xx with exponential backoff; fail fast on 4xx client errors
Capture the response body (it contains an error.code) by calling the API directly with curl for a richer diagnosis

Example fix

// before: retries everything blindly
await client.upload(req);
// after: classify by HTTP status parsed from the thrown message
try {
  await client.upload(req);
} catch (err) {
  const m = /HTTP (\d{3})/.exec(String(err.message));
  const status = m ? Number(m[1]) : 0;
  if (status === 429 || status >= 500) await backoffRetry(() => client.upload(req));
  else throw err; // 401/403/413 are not retryable
}

Defensive patterns

Strategy: try-catch

Validate before calling

// validate credential shape before uploading
if (!/^sk-[A-Za-z0-9_-]+$/.test(key)) {
  throw new Error("OPENAI_API_KEY does not look like a platform key");
}

Type guard

function isRetryableHttpStatus(err: unknown): boolean {
  const m = /HTTP (\d{3})/.exec(err instanceof Error ? err.message : "");
  if (!m) return false;
  const s = Number(m[1]);
  return s === 429 || s >= 500;
}

Try / catch

try {
  await client.upload(req);
} catch (err) {
  if (isRetryableHttpStatus(err)) await withBackoff(() => client.upload(req));
  else throw err; // 401/403/413 need config/data changes, not retries
}

Prevention

Verify the API key with a cheap GET /v1/models call at startup
Keep image payloads under the Files API size limit; compress before upload
Back off on 429 instead of hammering the API
Watch status.openai.com during incidents before assuming client error

When it happens

Trigger: client.upload() receives response.ok === false from POST /v1/files. Typical statuses: 401 (invalid/expired API key), 403 (key lacks files scope or org blocked), 413 (file exceeds size limit), 429 (rate limited), 5xx (OpenAI outage).

Common situations: Rotated or revoked OPENAI_API_KEY; uploading an image larger than the Files API limit; hitting org rate limits during batch uploads; OpenAI incident causing 5xx responses.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/40d4b846b076badd. Report an issue: GitHub.