# API Errors Reference

Use this page to diagnose failed API calls. Start with the HTTP status, then inspect the response body and endpoint-specific docs.


> For a guided checklist across API, deliverability, DNS, and integration issues, see [Troubleshooting](/docs/troubleshooting).


---

## Error Format {{ id: 'error-format' }}

Error responses may vary by endpoint age, but you should expect one of these shapes:

```json
{
  "error": "Unauthorized"
}
```

```json
{
  "errors": [
    {
      "field": "email",
      "message": "is invalid"
    }
  ]
}
```

Your integration should log:

- HTTP status code
- Endpoint path and method
- Response body
- Bento site UUID
- A redacted request body

Never log publishable keys, secret keys, full Basic auth headers, or user-sensitive event details.

---

## Status Codes {{ id: 'status-codes' }}

| Status | Common cause | Suggested action |
| --- | --- | --- |
| `400` | Missing required fields, invalid JSON, wrong field type. | Compare your payload to the endpoint schema and simplify to the minimum valid request. |
| `401` | Missing auth, bad Basic auth encoding, wrong keys, or missing `site_uuid`. | Rebuild the Basic auth header and confirm the site UUID. |
| `403` | Missing `User-Agent`, blocked request, or account access issue. | Add a real `User-Agent`, verify account access, and contact support if it persists. |
| `404` | Wrong endpoint path or method. | Check the endpoint path under `/api/v1` and use the documented method. |
| `422` | Accepted request shape but invalid business rule. | Check sender, email, tag, field, and template constraints. |
| `429` | Too many requests or email sends. | Slow down and retry with exponential backoff. |
| `5xx` | Temporary infrastructure issue. | Retry later with backoff and check [Bento status](https://status.bentonow.com). |

---

## Validation Errors {{ id: 'validation-errors' }}

Most validation failures come from one of these issues:

- Email address is missing or malformed.
- Required wrapper key is missing, such as `events`, `subscribers`, or `emails`.
- A field value is nested where the endpoint only accepts flat values.
- A tag list is sent in the wrong format.
- A sender email is not configured as an author in Bento.
- A transactional email body is empty or unsafe.

Reduce the payload to the smallest valid example from the endpoint page, then add fields back one at a time.

---

## Authentication Errors {{ id: 'authentication-errors' }}

For `401` responses, check these in order:

1. The URL includes `site_uuid=YOUR_SITE_UUID`.
2. Basic auth encodes `publishable_key:secret_key` with the colon.
3. The keys and site UUID belong to the same Bento site.
4. The request is sent server-side, not from a browser.
5. The `Authorization` header is not line-wrapped or truncated.

```bash
echo -n "your_publishable_key:your_secret_key" | base64
```

---

## Blocked Requests {{ id: 'blocked-requests' }}

If you receive HTML instead of JSON, or a `403` before your request reaches Bento, the usual issue is a missing or generic `User-Agent`.

```bash
-H 'User-Agent: AcmeCRM/1.0'
```


> ⚠️ **Warning**
> Some HTTP clients set a user agent automatically, but direct HTTP integrations should set one explicitly.


---

## Rate Limits {{ id: 'rate-limits' }}

When you receive `429`, do not retry immediately in a loop. Use exponential backoff and reduce concurrency.

Good defaults:

- Batch imports: send fewer records per request and add a delay between batches.
- Transactional emails: queue sends in your application and let them drain steadily.
- Polling: replace polling with events, webhooks, or scheduled syncs where possible.

Endpoint-specific limits override these general guidelines.

---

## Spam And Abuse Blocks {{ id: 'spam-and-abuse-blocks' }}

Bento may slow down or block risky transactional sends to protect your account and other Bento senders. Common causes include:

- User-controlled names or fields injected into transactional content.
- URL shorteners.
- Suspicious links.
- Emojis or unusual symbols in security-sensitive transactional emails.
- Repeated requests from an unprotected form or invite endpoint.

If this happens, remove risky personalization, rate limit the triggering action, and contact support with a redacted example.

---

## Endpoint-Specific Failures {{ id: 'endpoint-specific-failures' }}

| Endpoint | Common failure | Fix |
| --- | --- | --- |
| `/batch/events` | Missing `events` wrapper, missing `type`, missing `email`, or nested values inside `fields`. | Send `events: [{ type, email }]`. Put flat profile data in `fields` and nested event context in `details`. |
| `/batch/subscribers` | Missing `subscribers` wrapper or tag lists in an unexpected format. | Send `subscribers: [{ email }]`. Use comma-separated `tags` and `remove_tags` unless your SDK documents arrays. |
| `/batch/emails` | Sender is not an author, email body is empty, or unsafe personalization triggered abuse controls. | Confirm `from` is an author, send valid `html_body`, avoid user-controlled content in security-sensitive emails. |
| `/fetch/search` | Endpoint returns unauthorized or unavailable for the account. | This endpoint is Enterprise-gated. See [Plans and API access](/docs/api/access). |
| `/fetch/tags` | Applying a tag to a subscriber fails because this endpoint manages tag definitions only. | Use [Subscriber Commands](/docs/subscribers#run-command) or [Import Subscribers](/docs/subscribers#import-subscribers) to apply tags to people. |
| `/fetch/fields` | Field exists but values do not update on a subscriber. | This endpoint creates field definitions. Send field values through subscribers, events, forms, or integrations. |
| `/stats/*` | Requests succeed in development but fail in the browser. | Keep stats calls server-side so credentials stay private. |

When the response body is unclear, log the endpoint, method, status code, site UUID, and a redacted payload. That is usually enough for support to trace the request.

---

## Debug Checklist {{ id: 'debug-checklist' }}

Before escalating:

1. Reproduce with cURL.
2. Confirm `User-Agent`, auth, and `site_uuid`.
3. Try the smallest example payload from the endpoint page.
4. Check whether the user or sender is unsubscribed, suppressed, blocked, or unapproved.
5. Check [status.bentonow.com](https://status.bentonow.com).
6. Send support the endpoint, timestamp, site UUID, status code, and redacted response body.

## Related docs

- [API Conventions](/docs/api/conventions)
- [Authentication](/docs/authentication)
- [Troubleshooting](/docs/troubleshooting)
- [Spam API Overview](/docs/spam-api-overview)