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.

Error Format

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

Code

{
  "error": "Unauthorized"
}

Code

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

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.

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

For 401 responses, check these in order:

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

Code

echo -n "your_publishable_key:your_secret_key" | base64

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.

Code

-H 'User-Agent: AcmeCRM/1.0'

Some HTTP clients set a user agent automatically, but direct HTTP integrations should set one explicitly.

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

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

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.
`/fetch/tags`	Applying a tag to a subscriber fails because this endpoint manages tag definitions only.	Use Subscriber Commands or 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

Before escalating:

Reproduce with cURL.
Confirm User-Agent, auth, and site_uuid.
Try the smallest example payload from the endpoint page.
Check whether the user or sender is unsubscribed, suppressed, blocked, or unapproved.
Check status.bentonow.com.
Send support the endpoint, timestamp, site UUID, status code, and redacted response body.