> ## Documentation Index
> Fetch the complete documentation index at: https://inbound.new/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Comprehensive list of API error codes and their meanings

# Error Codes

The Inbound API returns standard HTTP status codes to indicate success or failure. Error responses include a JSON object with an `error` field describing the issue.

## HTTP Status Codes

| Status Code | Meaning | Description |
| - | - | - |
| `200` | Success | Request completed successfully |
| `400` | Bad Request | Invalid request parameters or missing required fields |
| `401` | Unauthorized | Invalid or missing API key |
| `403` | Forbidden | The API key or account is not allowed to do this (for example, sending is paused) |
| `404` | Not Found | Requested resource does not exist |
| `422` | Unprocessable Entity | The email provider rejected the message; retrying the same message will not succeed |
| `429` | Too Many Requests | Rate limit exceeded (100 requests/second per account across E2 endpoints) |
| `500` | Internal Server Error | Server error occurred |

## Common Error Types

### Authentication Errors (401)

* **`Unauthorized`** - Missing or invalid API key
* **`Invalid API key`** - API key format is incorrect or expired

### Validation Errors (400)

#### Missing Required Fields

* **`Missing required fields: from and to are required`** - Email sending
* **`Missing required fields: apiKey and to are required`** - Demo requests
* **`Missing required fields`** - General validation failure

#### Invalid Formats

* **`Invalid email format`** - Email address doesn't match expected pattern
* **`Invalid email format: [email]`** - Specific email address validation
* **`Invalid webhook URL format`** - Webhook URL validation failure
* **`Invalid scheduled_at`** - Date/time format is incorrect
* **`Invalid schedule time`** - Scheduled time is in the past or too far in future

#### Configuration Errors

* **`Invalid endpoint type`** - Unsupported endpoint type specified
* **`Invalid configuration`** - Endpoint configuration validation failed
* **`Webhook URL is required`** - Missing webhook URL for webhook endpoints
* **`Forward-to email address is required`** - Missing email for forwarding endpoints
* **`Invalid forward-to email address format`** - Invalid forwarding email format

#### Parameter Errors

* **`Invalid limit parameter`** - List limit must be 1-100
* **`Invalid offset parameter`** - Offset must be non-negative
* **`Invalid email ID provided`** - Email ID format is incorrect
* **`Invalid webhook format`** - Unsupported webhook payload format

### Sending Errors (403, 422)

* **`Sending is paused for this account. Please contact support.`** (403) - Sending is paused or suspended for your account; retrying will not help until it is resumed
* **`Email rejected by the email provider: [reason]`** (422) - The provider refused this message (for example, an invalid header or content it does not accept). Fix the message before sending it again
* **`Email rejected by the email provider as invalid: [reason]`** (422) - The provider considered the request invalid
* **`The custom MAIL FROM domain for this sender is not verified`** (422) - Verify the sending domain's MAIL FROM records

### Resource Errors (404)

* **`Email not found`** - Email doesn't exist or user lacks access
* **`Endpoint not found`** - Endpoint doesn't exist or access denied
* **`Scheduled email not found`** - Scheduled email not found or unauthorized
* **`Original email not found`** - Cannot reply to non-existent email

### Rate Limiting (429)

* **`Too Many Requests`** - Too many requests (limit: 100 per second per account across E2 endpoints)
* **`Rate limit exceeded. Maximum 100 requests per second. Retry after 1 seconds.`** - Example rate limit message; the retry delay varies
* **`Sending rate limit reached. Please try again later.`** - The email provider is throttling sends; retry with backoff
* **`Email sending limit reached. Please upgrade your plan to send more emails.`** - Your plan's sending limit is used up

### Server Errors (500)

* **`Failed to send email. Please try again later.`** - A temporary failure while sending; retry with backoff. Rejections of the message itself return 422 instead (see Sending Errors)
* **`Failed to schedule email`** - Email scheduling failed
* **`Failed to cancel scheduled email`** - Cancellation operation failed
* **`Failed to test endpoint`** - Endpoint testing failed

## Error Response Format

All error responses follow this structure:

```json theme={null}
{
  "error": "Error description",
  "message": "Additional context (optional)",
  "details": "Technical details (optional)"
}
```

## Rate Limit Headers

When approaching or exceeding rate limits, responses include headers:

| Header | Description |
| - | - |
| `ratelimit-limit` | Maximum requests per window |
| `ratelimit-remaining` | Requests remaining in current window |
| `ratelimit-reset` | Seconds until limit resets |
| `retry-after` | Seconds to wait before retry (429 only) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.