Every error code with what to do about it

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

Last updated April 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 bav_live_... 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