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 |
| { "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.