Skip to main content

​
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. 
{
  "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: 
{
  "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 codeError codeDescription
400bad_requestThe request body is malformed or missing required fields.
400validation_errorOne or more parameters failed validation. Check the details array.
401unauthorizedThe API key is missing, invalid, or expired.
403forbiddenThe API key does not have the required scope for this endpoint.
404not_foundThe requested resource does not exist or has been deleted.
409conflictThe request conflicts with the current state (e.g., duplicate webhook URL).
422unprocessable_entityThe request is well-formed but cannot be processed (e.g., regenerating a summary for a meeting still in progress).
429rate_limit_exceededYou have exceeded your plan’s rate limit.
500internal_errorAn unexpected error occurred on our side. These are automatically reported.
503service_unavailableThe 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. 
{
  "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. 
{
  "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. 
{
  "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 or update your existing key.

​
404 Not Found

The resource you requested does not exist. 
{
  "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. 
{
  "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. Check the Retry-After header for the recommended wait time.

​
500 Internal Error

An unexpected error occurred on our servers. 
{
  "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 with the request_id. 
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}")

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}`);
  }
}
Always log the request_id from error responses. Include it when contacting support so we can trace the exact request in our systems.