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.

Error Format

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

{
  "error": "Unauthorized"
}

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

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:

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.

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.

-H 'User-Agent: AcmeCRM/1.0'

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.

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.
6. Send support the endpoint, timestamp, site UUID, status code, and redacted response body.

Related docs

• API Conventions
• Authentication
• Troubleshooting
• Spam API Overview