Handle upload errors before the workflow retries blindly
Structured errors make file-to-URL workflows debuggable. Branch on the error code, log the file context, and retry only when the failure is actually transient.
Separate fixable configuration errors from retryable platform errors.
Blind retries waste workflow runs and can create duplicate files. Most errors should either ask the builder to change input or wait for a rate-limit window.
Authentication
`unauthorized` and `forbidden` mean the key, account, or policy must be fixed before retrying.
Validation
`missing_file`, `unsupported_type`, and `invalid_expiry` mean the request shape or file policy is wrong.
Limits
`file_too_large` and `rate_limited` should expose enough context for the workflow to branch or delay.
Log the fields that explain the failed file handoff.
Useful logs should include request ID, source workflow, filename, content type, size, expiry, and destination step. Do not log API keys.
Request ID
Expose a request identifier when possible so support can connect the client error to server logs.
File context
Keep filename, size, type, and expiry near the workflow execution record.
Destination status
If the upload succeeded but the next API failed, log the downstream response separately from the GetFileURL response.
Retry only after the cause matches a retryable class.
A rate limit or temporary platform issue can be retried after delay. Missing files, bad auth, unsupported type, and invalid expiry need request changes.
Retry with backoff
Use exponential backoff for temporary availability or rate-limit cases.
Do not retry bad input
Fix the request when the file, field, type, or expiry is invalid.
Avoid duplicate cleanup
When retrying upload or delete branches, keep file IDs and idempotency context visible.
Copy the same upload shape into code or workflow steps
Use the same endpoint from a shell, backend route, worker, or automation code step. Upload the file, set expiry, then map the returned URL.
JavaScript branch
upload exampleif (!res.ok) {
const body = await res.json().catch(() => null);
const code = body?.error?.code ?? `http_${res.status}`;
throw new Error(`GetFileURL upload failed: ${code}`);
}Answers before the workflow breaks
What error should a missing API key return?
A missing or invalid bearer key should return an unauthorized error and no public file URL should be created.
Should I retry every failed upload?
No. Retry only transient errors such as rate limits or temporary availability. Request validation and auth failures need a fix first.
What should I show in workflow logs?
Show the error code, message, request ID if available, filename, content type, size, expiry, and the workflow step that failed.