Every error code with what to do about it

JSON error responses with descriptive messages and standard HTTP status codes.

Last updated May 7, 2026

Error Format

Every API error returns a consistent JSON body with an HTTP status code, error code, and human-readable message.

{
  "error": {
    "code": "validation_error",
    "message": "The 'toEmail' field must be a valid email address.",
    "details": {}
  }
}

Error Codes

400Bad Request--bad_request

The request body is malformed or missing required fields. Check that your JSON is valid and all required fields are present.

401Unauthorized--unauthorized

Missing or invalid API key. Ensure the Authorization header is set to Bearer bm_... with a valid key.

403Forbidden--forbidden

The API key does not have permission for this action. Check key permissions in Settings > API Keys. Create a new key with the required scope.

404Not Found--not_found

The requested resource does not exist. Verify the resource ID. It may have been deleted or belongs to a different account.

409Conflict--conflict

The resource already exists or the operation conflicts with the current state. Check for duplicate resources. Use idempotency keys for retries.

422Validation Error--validation_error

One or more fields failed validation. Read the details object for field-level errors. Fix the invalid fields and retry.

429Rate Limited--rate_limited

Too many requests. Back off and retry after the Retry-After header value (in seconds). Implement exponential backoff.

500Internal Error--internal_error

An unexpected error occurred on our end. Retry with exponential backoff. If it persists, contact support@bavimail.com with the X-Request-Id header value.

Best Practices

4xx errors are client errors -- fix the request before retrying.
5xx errors are server errors -- retry with exponential backoff.
Never retry 401 or 403 without fixing the API key or permissions first.
Always log the X-Request-Id response header for debugging with support.

Include the X-Request-Id header value when contacting support for faster resolution.

API Explorer

Domain Verification