HTTP status codes returned by the Poptin API, what each means, and how clients should react. Pairs with the standard response envelope.
Every response from the Poptin API pairs an HTTP status code with the standard JSON response envelope. The status code tells you how to react - retry, back off, fix input, escalate - and the envelope's message and errors fields tell you why. Read them together.
All operations are served from https://api.popt.in/v1 and authenticated with a pk_live_ bearer key from My Account → API & Connections → API Keys.
Status codes
| Code | Name | Meaning |
|---|---|---|
200 | OK | Synchronous success. Also used as the idempotent response for a poptin stats refresh that is already in progress. |
201 | Created | A new resource was created - for example a contact or a custom property. |
202 | Accepted | Work was accepted and will finish in the background. Poll the returned job. See Async job polling and Async jobs. |
204 | No Content | Success with no response body. Returned by successful deletes. |
400 | Bad Request | The request is malformed and cannot be processed. |
401 | Unauthorized | The token is missing, malformed, or invalid, or the account behind it is inactive or deleted. |
403 | Forbidden | The token is valid but the account is restricted from performing this operation. |
404 | Not Found | The resource does not exist, or does not exist within the authenticated account. |
406 | Not Acceptable | The operation is not allowed on this resource - for example deleting a default property. |
409 | Conflict | The request conflicts with current state - for example a bulk job cannot start because of concurrency, or a template email hit the duplicate-send window. |
422 | Unprocessable Entity | Validation failed, or the action is not allowed in the resource's current state. errors lists the specifics. |
423 | Locked | The account is being processed and the operation is temporarily blocked. Retry after a short delay. |
429 | Too Many Requests | A rate limit was exceeded, or a per-operation cooldown (such as poptin stats refresh) is active. Honor the Retry-After header when present. See Rate Limits. |
500 | Internal Server Error | An unexpected error on Poptin's side. Retry after a delay; if it persists, contact support. |
Client tip: branch on the status code class first (2xx, 4xx, 5xx), then use the specific code to decide the action, and finally read the envelope for the human-readable reason.