Every error code with what to do about it

Last updated May 29, 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

400 Bad Request--bad_request

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

401 Unauthorized--unauthorized

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

403 Forbidden--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.

404 Not Found--not_found

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

409 Conflict--conflict

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

422 Validation Error--validation_error

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

429 Rate Limited--rate_limited

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

500 Internal Error--internal_error

An unexpected error occurred on our end. Retry with exponential backoff. If it persists, contact [email protected] 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.