This page lists the HTTP status codes returned by the Blueshift API and how to interpret them. Individual endpoint responses may include more specific error details — see the response body and the endpoint's own reference page for context.

Status code classes

The first digit of an HTTP status code defines the response class:

Class	Meaning
2xx	Success. The request was received, understood, and processed.
4xx	Client error. The request was invalid, unauthorized, or could not be completed as sent. Fix the request and retry.
5xx	Server error. Something went wrong on Blueshift's side. Retry with backoff, and contact support if the issue persists.

Common error responses

Not every code applies to every endpoint. Refer to the endpoint reference page for endpoint-specific behavior.

Status code	Description	Example responses
400 Bad Request	The request is invalid due to missing or incorrect parameters. This includes missing fields, invalid values, formatting issues, or conflicts such as duplicate data.	`{ "errors": { "name": ["can't be blank"] } }` `{ "errors": { "startdate": ["can't be blank"] } }`
401 Unauthorized	API authentication failed due to an invalid or missing API key.	`{ "message": "Not authorized" }`
403 Forbidden	The API key does not have sufficient permissions to perform this action.	`{ "message": "Permission denied" }`
404 Not Found	The specified campaign was not found. Verify the campaign UUID.	`{ "message": "Campaign not found" }`
422 Unprocessable Entity	The campaign cannot be paused due to its current status (e.g., already completed or archived). One or more scheduling parameters may be invalid (if applicable).	`{ "message": "Campaign cannot be paused in its current status." }` `{ "message": "Invalid schedule values" }`
429 Too Many Requests	The request limit has been exceeded. Reduce request frequency.	`{ "message": "Rate limit exceeded" }`
500 Internal Server Error	An unexpected server error occurred. Contact support if the issue persists.	`{ "message": "Internal Server Error - Please contact support for more information." }`
502 Bad Gateway	The server received an invalid response. Retry the request.	`{ "message": "Bad Gateway - Please retry the request." }`
503 Service Unavailable	The service is temporarily unavailable. Try again later.	`{ "message": "Service Unavailable - The service is temporarily unavailable. Try again later." }`
504 Gateway Timeout	The server took too long to respond. Retry the request with exponential backoff.	`{ "message": "Gateway Timeout - The server took too long to respond. Retry with exponential backoff." }`

Retry guidance

For 5xx and 429 errors, retry with exponential backoff — wait 1 second before the first retry, then 2, 4, 8, and so on. Cap retries at a reasonable number (typically 5) and add jitter to avoid synchronized retry storms.

For 4xx errors other than 429, fix the request before retrying. Repeating an unmodified request will produce the same error.

💬
Need help? For support, see Get in touch.