Troubleshooting

The PredictHQ API uses conventional HTTP status codes to indicate the success or failure of an API request. If you receive an error, this is what it means:

HTTP Status Code	Description
Bad Request 400	The request contains invalid parameters, or invalid or incomplete data.
Unauthorized 401	You failed to provide a valid Authorization header, or your credentials are invalid or expired.
Payment Required 402	Your subscription has expired.
Forbidden 403	You tried to perform an action that is not authorized. E.g. you failed to request the required scope.
Not Found 404	The resource or endpoint does not exist. Please ensure the URL is correct. Note that you may need to add a trailing slash to the URL path.
Too Many Requests 429	You have reached your subscription (or global) rate limit. Please implement exponential backoffs and retries and take care not to send too many requests in a short period of time.
Server Error 5xx	An unexpected error occurred on our end. These errors are transient — retry the request using exponential backoff.
Service Unavailable 503	The API has been switched to maintenance mode for a major or complex release.

Retrying Failed Requests

As with any API exposed over the public internet, some requests may fail transiently and should be retried automatically. We recommend implementing exponential backoff with jitter for all 5xx errors and 429 Too Many Requests responses.

Retry up to 3 times before failing the request and handling it accordingly.

Backoff schedule (with jitter):

Attempt	Base delay	Jitter
1st retry	1 second	±500ms random
2nd retry	2 seconds	±500ms random
3rd retry	4 seconds	±500ms random

Jitter prevents multiple clients from retrying in lockstep, which can amplify load on the API. A simple approach is to add a random value between 0 and 1000ms to each base delay.

Do not retry 4xx errors other than 429 — these indicate a problem with the request itself (invalid parameters, authentication failure, insufficient permissions) that retrying will not resolve.