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

# Errors

> Understand the error codes returned by the Mavio API and how to handle them.

## Error response format

All errors follow a consistent JSON structure. Every error includes a machine-readable `code`, a human-readable `message`, and a unique `request_id` you can reference when contacting support.

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Meeting with ID mtg_xyz789 was not found.",
    "request_id": "req_abc123def456"
  }
}
```

For validation errors, an additional `details` array identifies the specific fields that failed:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "One or more request parameters are invalid.",
    "request_id": "req_abc123def456",
    "details": [
      {
        "field": "limit",
        "message": "Must be an integer between 1 and 100."
      },
      {
        "field": "from",
        "message": "Must be a valid ISO 8601 date string."
      }
    ]
  }
}
```

## HTTP status codes

| Status code | Error code             | Description                                                                                                        |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **400**     | `bad_request`          | The request body is malformed or missing required fields.                                                          |
| **400**     | `validation_error`     | One or more parameters failed validation. Check the `details` array.                                               |
| **401**     | `unauthorized`         | The API key is missing, invalid, or expired.                                                                       |
| **403**     | `forbidden`            | The API key does not have the required scope for this endpoint.                                                    |
| **404**     | `not_found`            | The requested resource does not exist or has been deleted.                                                         |
| **409**     | `conflict`             | The request conflicts with the current state (e.g., duplicate webhook URL).                                        |
| **422**     | `unprocessable_entity` | The request is well-formed but cannot be processed (e.g., regenerating a summary for a meeting still in progress). |
| **429**     | `rate_limit_exceeded`  | You have exceeded your plan's [rate limit](/api-reference/rate-limits).                                            |
| **500**     | `internal_error`       | An unexpected error occurred on our side. These are automatically reported.                                        |
| **503**     | `service_unavailable`  | The API is temporarily unavailable due to maintenance or high load.                                                |

## Error handling guide

### 400 Bad Request

Your request is malformed. Check the request body and query parameters.

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "Request body must be valid JSON.",
    "request_id": "req_d1e2f3g4h5"
  }
}
```

**Fix**: Ensure you are sending valid JSON with the `Content-Type: application/json` header.

### 401 Unauthorized

The API cannot authenticate your request.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Please check your credentials.",
    "request_id": "req_a1b2c3d4e5"
  }
}
```

**Fix**: Verify your API key is correct, not expired, and included as `Authorization: Bearer <key>`.

### 403 Forbidden

Your API key is valid but lacks the required scope.

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "Your API key does not have the 'meetings:write' scope required for this endpoint.",
    "request_id": "req_f6g7h8i9j0"
  }
}
```

**Fix**: Create a new API key with the necessary [scopes](/api-reference/authentication#scopes) or update your existing key.

### 404 Not Found

The resource you requested does not exist.

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Meeting with ID mtg_xyz789 was not found.",
    "request_id": "req_k1l2m3n4o5"
  }
}
```

**Fix**: Verify the resource ID is correct. If the resource was recently deleted, it may no longer be accessible.

### 429 Rate Limit Exceeded

You are sending too many requests.

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded the rate limit of 300 requests per minute. Please retry after 8 seconds.",
    "request_id": "req_p6q7r8s9t0"
  }
}
```

**Fix**: Implement [exponential backoff with jitter](/api-reference/rate-limits#retry-strategy). Check the `Retry-After` header for the recommended wait time.

### 500 Internal Error

An unexpected error occurred on our servers.

```json theme={null}
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Our team has been notified.",
    "request_id": "req_u1v2w3x4y5"
  }
}
```

**Fix**: Retry the request after a short delay. If the issue persists, [contact support](mailto:api-support@mavioapp.com) with the `request_id`.

## Recommended error handling

<CodeGroup>
  ```python Python theme={null}
  import mavio

  client = mavio.Client(api_key="mvo_live_abc123")

  try:
      meeting = client.meetings.get("mtg_xyz789")
  except mavio.NotFoundError as e:
      print(f"Meeting not found: {e.message}")
  except mavio.AuthenticationError as e:
      print(f"Auth error: {e.message}")
  except mavio.RateLimitError as e:
      print(f"Rate limited. Retry after {e.retry_after}s")
  except mavio.APIError as e:
      print(f"API error [{e.status_code}]: {e.message}")
      print(f"Request ID: {e.request_id}")
  ```

  ```javascript Node.js theme={null}
  import Mavio from '@mavio-ai/sdk';

  const client = new Mavio({ apiKey: 'mvo_live_abc123' });

  try {
    const meeting = await client.meetings.get('mtg_xyz789');
  } catch (error) {
    if (error instanceof Mavio.NotFoundError) {
      console.log(`Meeting not found: ${error.message}`);
    } else if (error instanceof Mavio.AuthenticationError) {
      console.log(`Auth error: ${error.message}`);
    } else if (error instanceof Mavio.RateLimitError) {
      console.log(`Rate limited. Retry after ${error.retryAfter}s`);
    } else if (error instanceof Mavio.APIError) {
      console.log(`API error [${error.status}]: ${error.message}`);
      console.log(`Request ID: ${error.requestId}`);
    }
  }
  ```
</CodeGroup>

<Tip>
  Always log the `request_id` from error responses. Include it when contacting support so we can trace the exact request in our systems.
</Tip>