Errors, Retries and Timeouts

Temporary errors such as 429, 500, 502, 503 and 504, or a dropped connection, can occur on any request. When polling GET /api/v3/predictions/{id}/result, retry these with exponential backoff (honor Retry-After) and keep polling until the task reaches a terminal status (completed, failed, cancelled, timeout or deleted). Tasks can run for a long time, so do not give up just because your own clock ran out.

Do not automatically retry the submit POST. If the connection drops or you get a 5xx and you did not receive a task id, the task may still have been created and billed. Before submitting again, check your recent predictions for a matching task. Only resubmit if none exists. If you have a task id, keep polling it instead of resubmitting.

A client-side timeout does not mean the task failed or was cancelled.

Polling the result

Put a timeout on each HTTP request (for example 30 to 60 seconds) so a stalled connection does not hang your program. That timeout bounds one request, not the task. Do not set an overall deadline on polling unless you accept that the task may still finish after you stop watching. If you stop polling yourself, keep the task id so you can check the result later.

Submitting a task

The submit request is sent once. If it fails before you receive a task id:

1. Open History, or list recent predictions with POST /api/v3/predictions (filter by model and created_after).
2. If a matching task exists, use its id and poll it.
3. Only if none exists, submit again.

If a response contains a task id, keep polling that id instead of resubmitting.

For long-running work you can also receive the result by webhook instead of polling.

Related Pages

• Submit Task
• Get Result
• Error Codes
• Troubleshooting Guide