Error Codes

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "invalid_coordinates",
    "message": "Latitude must be between -90 and 90",
    "param": "coordinates.latitude",
    "request_id": "req_abc123xyz"
  }
}

Authentication Errors (401)

Payment Errors (402)

Example Response

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient credit balance. Current balance: 0, required: 1",
    "current_balance": 0,
    "required_credits": 1,
    "purchase_url": "https://developers.sealegs.ai/dashboard#billing"
  }
}

Authorization Errors (403)

Not Found Errors (404)

Validation Errors (400)

Rate Limit Errors (429)

Example Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "retry_after": 30
  }
}

Rate limit responses include helpful headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1701432060
Retry-After: 30

Server Errors (500)

Handling Errors

Best Practices

• Always check the HTTP status code first
• Use the error.code field for programmatic handling
• Display error.message to users when appropriate
• Log the request_id for debugging and support
• Implement exponential backoff for retries

Example Error Handling (Python)

import requests
import time

def create_spotcast(data):
    response = requests.post(
        "https://api.sealegs.ai/v3/spotcast",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=data
    )

    if response.status_code == 202:
        return response.json()

    error = response.json().get("error", {})

    if response.status_code == 401:
        raise AuthenticationError(error.get("message"))

    if response.status_code == 402:
        raise InsufficientBalanceError(
            error.get("message"),
            balance=error.get("current_balance")
        )

    if response.status_code == 429:
        retry_after = error.get("retry_after", 60)
        time.sleep(retry_after)
        return create_spotcast(data)  # Retry

    if response.status_code >= 500:
        # Server error - retry with backoff
        raise ServerError(error.get("message"))

    # Validation or other client error
    raise APIError(error.get("code"), error.get("message"))

Example Error Handling (JavaScript)

async function createSpotcast(data) {
  const response = await fetch('https://api.sealegs.ai/v3/spotcast', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (response.status === 202) {
    return response.json();
  }

  const { error } = await response.json();

  switch (response.status) {
    case 401:
      throw new AuthenticationError(error.message);

    case 402:
      throw new InsufficientBalanceError(error.message, error.current_balance);

    case 429:
      const retryAfter = error.retry_after || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      return createSpotcast(data); // Retry

    case 500:
    case 502:
    case 503:
      throw new ServerError(error.message);

    default:
      throw new APIError(error.code, error.message);
  }
}