> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors and response formats

> Look up common Notifly API response formats and HTTP status codes.

## Response formats

A common error response includes `success`, `code`, and `error`.

```json theme={null}
{ "success": false, "code": 400, "error": "Bad request: details" }
```

Some endpoints return a shorter error response.

```json theme={null}
{ "error": "Bad request: details" }
```

A successful request may return a success flag.

```json theme={null}
{ "success": true }
```

Depending on the endpoint, the response may instead contain `data` and `error`.

```json theme={null}
{ "data": "...", "error": null }
```

## HTTP status codes

| Code | Name | What it means | What to do |
| -: | - | - | - |
| 200 | OK | The request succeeded. | Read the endpoint schema for the response. |
| 400 | Bad Request | A body, query, or path value is missing, invalid, or in the wrong format. | Correct the request and retry. |
| 401 | Unauthorized | The token is invalid or expired, or authentication failed. | Get a new token from `POST /authenticate` before retrying. |
| 403 | Forbidden | Your credentials lack access to the project or resource. | Check your permissions or request access. |
| 404 | Not Found | A resource such as a campaign or user could not be found. | Check the resource ID and path. |
| 405 | Method Not Allowed | The endpoint does not support the HTTP method. | Check the method in the endpoint reference. |
| 409 | Conflict | A resource already exists or its current state prevents the operation. | Check the resource state before retrying. |
| 413 | Payload Too Large | The request or batch exceeds a size limit. | Split the batch or send a smaller body. |
| 429 | Too Many Requests | The request exceeded a rate limit. | Retry with exponential backoff. |
| 500 | Internal Server Error | The server could not complete the request. | Retry if the operation is safe to repeat. Contact support if the error persists. |
| 501 | Not Implemented | The requested operation is unavailable. | Check the endpoint documentation for availability. |

## Example error responses

### 400 Bad Request

```json theme={null}
{ "success": false, "code": 400, "error": "Bad request: eventName missing" }
```

### 401 Unauthorized

```json theme={null}
{ "success": false, "code": 401, "error": "Unauthorized: Invalid token" }
```

### 413 Payload Too Large

```json theme={null}
{ "success": false, "code": 413, "error": "Payload too large" }
```

### 500 Internal Server Error

```json theme={null}
{ "success": false, "code": 500, "error": "Internal Server Error" }
```

## Handle failures

* If a token has expired, call `POST /authenticate` to get a new one before retrying.
* If a batch exceeds the endpoint limit, split the data into smaller requests. For example, some operations accept at most 1,000 records per request.
* Use exponential backoff on retryable errors such as `429` and some `500` responses.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.