​
Error Handling

The Meibel AI API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error due to the information provided (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with our servers.

​
HTTP Status Codes

CodeDescription
200 - OKThe request was successful.
201 - CreatedThe resource was successfully created.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
403 - ForbiddenThe API key doesn’t have permissions to perform the request.
404 - Not FoundThe requested resource doesn’t exist.
409 - ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
422 - Validation ErrorThe request was well-formed but was unable to be processed due to semantic errors.
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server ErrorsSomething went wrong on our end. (These are rare.)

​
Error Response Format

All API errors include a standard JSON response body that provides detailed information about the error:

{
  "error": {
    "message": "A human-readable error message",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "request_id": "req_123456789"
  }
}
FieldDescription
messageA human-readable message providing details about the error.
typeThe type of error returned.
codeA machine-readable code specifying the error type.
paramIf the error is parameter-specific, the parameter related to the error.
request_idA unique identifier for the request. This is helpful when contacting support.

​
Common Error Types

​
Authentication Errors

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "request_id": "req_123456789"
  }
}

​
Validation Errors

{
  "error": {
    "message": "The request was well-formed but was unable to be processed",
    "type": "validation_error",
    "code": "parameter_validation_failed",
    "param": "datasource_id",
    "details": [
      {
        "loc": ["body", "datasource_id"],
        "msg": "Field required",
        "type": "value_error.missing"
      }
    ],
    "request_id": "req_123456789"
  }
}

​
Rate Limit Errors

{
  "error": {
    "message": "Too many requests",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "request_id": "req_123456789"
  }
}

​
Error Handling in SDKs

Our official SDKs handle errors by throwing exceptions that you can catch and process:

# Python SDK Example
from meibelai import Meibelai, models
import os

client = Meibelai(
    api_key_header=os.getenv("MEIBELAI_API_KEY_HEADER", ""),
)

try:
    res = client.datasources.list()
    print(res)
except models.HTTPValidationError as e:
    # Handle validation error
    print(f"Validation error: {e.data}")
except models.APIError as e:
    # Handle API error
    print(f"API error: {e.message}, Status code: {e.status_code}")

​
Tips for Error Handling

Always implement proper error handling in your application to provide a good user experience and facilitate debugging.

1

Implement retry logic

Use exponential backoff for retrying failed requests, especially for rate limit errors (429)

2

Log request IDs

Always log the request_id from error responses to help with troubleshooting

3

Handle expected errors

Handle common error cases gracefully in your application

4

Provide user feedback

Translate API errors into helpful messages for your users

​
Getting Help

If you’re experiencing persistent errors or need help debugging an issue:

  1. Ensure you have the complete error message and request ID
  2. Check if there are any service disruptions on our status page
  3. Contact our support team at support@meibel.ai with details about the error