Skip to main content

​
Error Response Format

All API errors follow a consistent format: 
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_category",
    "code": "specific_error_code",
    "param": "field_name_if_applicable"
  }
}
FieldDescription
messageHuman-readable description of what went wrong
typeCategory of error (e.g., authentication_error, validation_error)
codeSpecific error code for programmatic handling
paramThe request parameter that caused the error (if applicable)

​
HTTP Status Codes

StatusDescription
200Success
201Created (for POST requests that create resources)
400Bad Request - Invalid parameters or malformed request
401Unauthorized - Invalid or missing API key
402Payment Required - Insufficient credits
403Forbidden - Access denied to resource
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our side
503Service Unavailable - Temporary outage

​
Error Types

​
Authentication Errors (401)

{
  "error": {
    "message": "Invalid API key. Ensure your key starts with 'mvra_live_' and has not been revoked.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}
CodeDescriptionSolution
missing_api_keyNo Authorization headerAdd Authorization: Bearer <key> header
invalid_api_keyKey format invalid or doesn’t existCheck key format starts with mvra_live_
revoked_api_keyKey has been revokedCreate a new API key

​
Validation Errors (400)

{
  "error": {
    "message": "Invalid value for 'model': must be one of ['mavera-1'].",
    "type": "invalid_request_error",
    "code": "invalid_model",
    "param": "model"
  }
}
CodeDescriptionSolution
invalid_modelInvalid model specifiedUse mavera-1
missing_fieldRequired field not providedInclude the required field
invalid_fieldField value is invalidCheck field requirements in API reference
invalid_personaPersona ID doesn’t existList personas to get valid IDs

​
Credit Errors (402)

{
  "error": {
    "message": "Insufficient credits. Please upgrade your subscription or wait for your next billing cycle.",
    "type": "insufficient_credits",
    "code": "credits_exhausted",
    "param": null
  }
}
CodeDescriptionSolution
credits_exhaustedNo credits remainingUpgrade plan or wait for reset
budget_exceededWorkspace/project budget limit hitIncrease budget or wait

​
Rate Limit Errors (429)

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}
Check the Retry-After header for how long to wait.

​
Not Found Errors (404)

{
  "error": {
    "message": "Thread not found",
    "type": "not_found_error",
    "code": "resource_not_found",
    "param": "thread_id"
  }
}

​
Server Errors (500, 503)

{
  "error": {
    "message": "An internal error occurred. Please try again later.",
    "type": "api_error",
    "code": "internal_error",
    "param": null
  }
}
If you receive 500 errors consistently, please contact support@mavera.io

​
Handling Errors in Code

from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI(
    api_key="mvra_live_your_key_here",
    base_url="https://app.mavera.io/api/v1",
)

try:
    response = client.responses.create(
        model="mavera-1",
        input=[{"role": "user", "content": "Hello"}],
        extra_body={"persona_id": "your_persona_id"},
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    # Handle invalid API key
except RateLimitError as e:
    print(f"Rate limited: {e}")
    # Implement backoff and retry
except APIError as e:
    if e.status_code == 402:
        print("Insufficient credits")
        # Handle billing issue
    elif e.status_code == 404:
        print("Resource not found")
        # Handle missing resource
    else:
        print(f"API error: {e}")
        # Log and retry for transient errors

​
Retry Strategy

For transient errors (429, 500, 503), implement exponential backoff: 
import time
import random

def retry_with_backoff(func, max_retries=5, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise

            # Check if retryable
            if hasattr(e, 'status_code') and e.status_code in [429, 500, 503]:
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                print(f"Attempt {attempt + 1} failed. Retrying in {delay:.1f}s...")
                time.sleep(delay)
            else:
                raise

​
Debugging Tips

Include request ID, timestamp, and full error response in logs for debugging.
The param field tells you exactly which field caused validation errors.
Keys must start with mvra_live_ and be exactly as copied from the dashboard.
Isolate issues by testing the raw API with curl before debugging SDK code.

​
Request IDs

Some error responses include a request_id (or similar) in the response headers or body. If present, include it when contacting support—it helps us locate the exact request in our logs. 
X-Request-ID: req_abc123xyz
Log this value in your application when errors occur. Example: 
# If the API returns X-Request-ID in headers
request_id = response.headers.get("X-Request-ID")
if not response.ok and request_id:
    log_error(f"Request failed: {request_id} - {response.text}")

​
Logging for Support

When reporting issues, provide structured information. Never log or share your full API key—only the prefix (e.g. mvra_live_abcd...).
FieldInclude
Error codeFrom error.code
Error messageFrom error.message
paramFrom error.param (for validation errors)
HTTP statuse.g. 401, 402, 429
Endpointe.g. /responses
TimestampWhen the error occurred
Request IDIf returned in headers
API key prefixFirst 10 characters only
For production error handling patterns, see Error Handling Patterns.

​
Getting Help

If you encounter persistent errors:
  1. Check our status page for outages
  2. Review the error message and code
  3. Contact support@mavera.io with:
    • Error message and code
    • Request details (endpoint, parameters)
    • Timestamp
    • Request ID (if available)
    • Your API key prefix (first 10 characters only)

Error Handling Patterns

Retries, backoff, user-facing messages

Authentication

Fix 401 errors

Rate Limits

Handle 429

Credits

Handle 402