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"
}
}
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 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. |
| 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.
{
"error": {
"code": "bad_request",
"message": "Request body must be valid JSON.",
"request_id": "req_d1e2f3g4h5"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
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"
}
}
request_id.
Recommended error handling
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}")
Always log the request_id from error responses. Include it when contacting support so we can trace the exact request in our systems.
