Common API errors

This guide helps you diagnose and resolve the most frequently encountered HTTP error responses when using Sender's REST API.

Symptoms

Your API request returns a 4xx or 5xx HTTP status code instead of the expected 200 or 201 response.

The response body contains a "success": false value or a "message" field describing the failure.

The errors object in the response body lists one or more fields that failed validation.

Your application receives no response or a timeout when calling https://api.sender.net/v2/ endpoints.

Possible Causes

Missing or invalid API token — The Authorization: Bearer {token} header is absent, malformed, or contains a revoked token, resulting in a 401 Unauthorized response.

Malformed request body or invalid parameters — Required fields are missing or contain incorrect data types, causing a 400 Bad Request or 422 Bad request parameters response with details in the message or errors field.

Rate limit exceeded — Too many requests were sent in a short period, triggering a 429 Too Many Requests response with rate limit details in the X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers.

Incorrect endpoint or resource ID — The request targets a nonexistent URL or references a resource ID that does not exist, returning a 404 Not Found response.

Server-side issue — A 5xx response indicates a temporary problem on Sender's servers, not an issue with your request.

Steps to Resolve

Step 1 — Fix authentication errors (401 Unauthorized)

If the API returns 401, verify that your request includes the Authorization header in the format Authorization: Bearer {token}. Confirm that the token has not been revoked by navigating to Account settings → API access tokens in your Sender dashboard. If the token is missing from the list, generate a new one and update the header in your application. Also verify that the request is sent over HTTPS — plain HTTP requests will fail.

Step 2 — Resolve validation errors (400 and 422)

For a 400 response, inspect the message field in the response body to identify the issue. For a 422 response, inspect the errors object — each key corresponds to a field name, and its value describes what is invalid. For example, "email": ["Required value, email"] means the email field was missing or not a valid email address. Correct the flagged fields in your request body and ensure required parameters like email for POST /v2/subscribers or title for POST /v2/groups are included.

Step 3 — Handle rate limiting (429 Too Many Requests)

When you receive a 429 response, read the Retry-After header to determine how many seconds to wait before retrying. Check X-RateLimit-Limit for your maximum requests per minute and X-RateLimit-Remaining for how many you have left. Implement exponential backoff in your code so that consecutive rate limit hits progressively increase the delay between retries. Avoid sending bulk requests in tight loops.

Step 4 — Correct endpoint and resource errors (404 Not Found)

A 404 response means the requested resource does not exist. Verify that the endpoint URL matches the documented paths — for example, https://api.sender.net/v2/subscribers not https://api.sender.net/v2/subscriber. If the endpoint includes a resource ID such as POST /v2/campaigns/{id}/send, confirm the {id} value corresponds to an existing resource in your account. Check for typos and ensure you are using the v2 base URL.

Step 5 — Address server errors (5xx)

A 5xx response indicates a server-side issue on Sender's end. Wait 30–60 seconds and retry the same request. If the error persists across multiple retries, contact Sender support at support@sender.net with the full request details, response body, and timestamps. Do not modify your request — the issue is not caused by your input.

Error Response Reference

400 — Bad Request — The request structure is valid but contains a logical error. The response body includes "success": false and a "message" field explaining the issue, such as "You must activate workflow first". Review the message value and correct the precondition or parameter it references.

401 — Unauthorized — Authentication failed. The Authorization: Bearer {token} header is missing, malformed, or contains an invalid token. Verify the token exists in Account settings → API access tokens and that the header format is correct.

404 — Not Found — The requested resource or endpoint does not exist. Verify the URL path and any resource IDs included in the request. Ensure you are using the https://api.sender.net/v2/ base URL.

422 — Bad Request Parameters — One or more parameters failed validation. The response body contains "message": "The given data was invalid." and an errors object where each key is a field name and each value is an array of validation messages. Fix the fields listed in the errors object and resend.

429 — Too Many Requests — The rate limit has been exceeded. The response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers. Wait the number of seconds specified in Retry-After before sending another request.

5xx — Server Error — A server-side error occurred on Sender's infrastructure. Retry the request after a short delay. If 5xx errors persist, contact Sender support with the request method, endpoint, and response timestamps.

How to Verify the Fix

After applying the fix, resend the original request and confirm you receive a 200 or 201 status code. Inspect the response body for "success": true and the expected data object. If the request created or updated a resource (such as a subscriber or group), navigate to the corresponding section in your Sender dashboard to confirm the change is reflected. If the error persists after following the resolution steps, contact Sender support with the request details and full response body.

Debugging Tips

Log full responses — Always log the HTTP status code, response headers, and the complete response body for every API call. This captures the message and errors fields needed for diagnosis.

Validate headers before sending — Confirm every request includes Authorization: Bearer {token}, Content-Type: application/json, and Accept: application/json. Missing any of these headers is a common source of 401 and 400 errors.

Test with cURL first — Reproduce the failing request using curl on the command line. This isolates whether the issue is in your application code or the request itself.

Monitor rate limit headers — Track X-RateLimit-Remaining in successful responses to anticipate 429 errors before they occur. Throttle your requests when the remaining count approaches zero.

Use HTTPS exclusively — All requests to https://api.sender.net/v2/ must use HTTPS. Requests sent over plain HTTP will fail silently or return unexpected errors.

Subscriber creation returns 422 with field-specific errors → The email field is either missing or not a valid email address. Inspect the errors object in the response to identify which parameter failed and correct its value.

Campaign send returns 400 with a precondition message → The campaign may not be fully configured. Check the message field for details such as "You must activate workflow first" and complete the required setup before retrying the POST /v2/campaigns/{id}/send request.

Pagination requests return empty data arrays → The requested page may exceed the total number of available pages. Check the meta.last_page value in previous responses and ensure your ?page parameter does not exceed it.

FAQs

How do I find the specific field that caused a 422 error?

Inspect the errors object in the response body. Each key in the object corresponds to a field name, and the value is an array describing what is invalid. For example, "email": ["Required value, email"] means the email field was missing or malformed.

My API token was working yesterday but now returns 401. What happened?

The token may have been revoked or deleted. Go to Account settings → API access tokens and verify the token still exists. If not, create a new one and update your application's Authorization header.

How long should I wait after a 429 rate limit error?

Check the Retry-After header in the response. It specifies the number of seconds to wait before retrying. Implement exponential backoff in your code so that consecutive rate limit hits increase the wait time progressively.

The API returns 200 but the data in Sender does not update. Why?

A 200 response confirms the request was accepted, but the data may take a moment to propagate. Refresh the relevant page in your Sender dashboard. If the data still does not appear, verify that the request body contained the correct field values and that you targeted the right resource ID.

I keep getting 500 Internal Server Error. Is it my fault?

A 500 error typically indicates a server-side issue on Sender's end, not a problem with your request. Retry the request after a short wait. If 500 errors persist across multiple requests, contact Sender support with the request details and timestamps.