Error Codes & Rate Limits

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "INVALID_DATETIME",
    "message": "The datetime field must be a valid ISO 8601 string.",
    "details": {
      "field": "datetime",
      "value": "not-a-date"
    }
  }
}

HTTP Status Codes

| Status | Meaning | |--------|---------| | 200 | Success | | 400 | Bad Request – Invalid parameters | | 401 | Unauthorized – Invalid or missing API key | | 403 | Forbidden – Key lacks required permissions | | 404 | Not Found – Resource doesn't exist | | 429 | Too Many Requests – Rate limit exceeded | | 500 | Internal Server Error | | 503 | Service Unavailable – Temporary outage |

Error Codes

Authentication Errors

| Code | Description | |------|-------------| | MISSING_API_KEY | Missing authentication. Provide either X-API-Key or Authorization: Bearer <jwt> | | INVALID_API_KEY | API key format is invalid | | EXPIRED_API_KEY | API key has expired | | REVOKED_API_KEY | API key has been revoked | | INSUFFICIENT_PERMISSIONS | Key lacks required permissions |

Validation Errors

| Code | Description | |------|-------------| | INVALID_DATETIME | Datetime is not valid ISO 8601 | | INVALID_LATITUDE | Latitude must be between -90 and 90 | | INVALID_LONGITUDE | Longitude must be between -180 and 180 | | INVALID_TIMEZONE | Unknown or invalid timezone | | INVALID_HOUSE_SYSTEM | Unsupported house system | | INVALID_ZODIAC | Unsupported zodiac system | | INVALID_BODY | Unknown celestial body | | DATETIME_OUT_OF_RANGE | Datetime outside supported range |

Rate Limiting Errors

| Code | Description | |------|-------------| | RATE_LIMIT_EXCEEDED | Too many requests | | QUOTA_EXCEEDED | Monthly fair-use threshold exceeded |

Resource Errors

| Code | Description | |------|-------------| | CHART_NOT_FOUND | Chart ID doesn't exist | | USER_NOT_FOUND | User account not found |

Rate Limits

AstroMCP uses credit-based rate limits. When you’re throttled you’ll receive 429 plus standard headers so your client can back off and retry safely.

Current Pro defaults:

• 600 credits/min
• 10 credits/sec burst

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1701388800
Retry-After: 2

| Header | Description | |--------|-------------| | X-RateLimit-Limit | Max credits per minute | | X-RateLimit-Remaining | Credits remaining this minute | | X-RateLimit-Reset | Unix timestamp when the limit resets | | Retry-After | Seconds to wait before retrying (present on 429) |

Handling Rate Limits

When you receive a 429 response:

1. Check the Retry-After header for seconds to wait
2. Implement exponential backoff
3. Consider caching responses
4. Reduce concurrency / batch requests when possible

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    const retryAfter = response.headers.get('Retry-After') || 1;
    await sleep(retryAfter * 1000 * Math.pow(2, i));
  }
  
  throw new Error('Max retries exceeded');
}

Datetime Range

AstroMCP supports datetimes from year 1 to 3000 CE.

Requests outside this range return DATETIME_OUT_OF_RANGE.

Note: accuracy is highest (ΔT precision) between 1600–2100 CE.

Support

If you encounter persistent errors, contact support@astromcp.io with:

• Your API key prefix (e.g., astro_sk_prod_...abc)
• Request ID from X-Request-ID header
• Full error response
• Timestamp of the error