Error Codes

HTTP status codes, error response shape, and troubleshooting guidance.

Error Response Shape

All error responses follow a consistent JSON structure. Every error includes a machine-readable status code, a human-readable message, and a unique request ID for debugging:

Error Response Structure
interface ErrorResponse {
  error: {
    status: number;    // HTTP status code
    message: string;   // Human-readable description
    requestId: string; // Unique ID for support debugging (req_...)
  };
}

Status Codes

400 Bad Request

The request body or query parameters are invalid. Check the message field for details on which parameter failed validation.

{
  "error": {
    "status": 400,
    "message": "Invalid value for 'sign': must be one of aries, taurus, ..., pisces",
    "requestId": "req_abc123def456"
  }
}

401 Unauthorized

The Authorization header is missing, malformed, or contains an invalid API key.

{
  "error": {
    "status": 401,
    "message": "Invalid or missing API key",
    "requestId": "req_abc123def456"
  }
}

403 Forbidden

Your API key is valid but your plan does not include access to this endpoint. Upgrade your plan to gain access.

{
  "error": {
    "status": 403,
    "message": "Endpoint requires Pro plan or higher",
    "requestId": "req_abc123def456"
  }
}

404 Not Found

The requested endpoint does not exist. Check the URL path against the API reference.

{
  "error": {
    "status": 404,
    "message": "Endpoint not found",
    "requestId": "req_abc123def456"
  }
}

408 Request Timeout

The request exceeded the 30-second timeout. This can happen with computationally intensive endpoints over large date ranges (eclipses, retrogrades).

{
  "error": {
    "status": 408,
    "message": "Request timed out after 30 seconds",
    "requestId": "req_abc123def456"
  }
}

429 Too Many Requests

Rate limit exceeded. Wait for the number of seconds specified in the Retry-After header before retrying.

{
  "error": {
    "status": 429,
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "requestId": "req_abc123def456"
  }
}

500 Internal Server Error

An unexpected error occurred. Include the requestId when contacting support.

{
  "error": {
    "status": 500,
    "message": "An unexpected error occurred",
    "requestId": "req_abc123def456"
  }
}

Common Troubleshooting

Getting 401 even though your key looks correct?

  • Ensure the header is exactly Authorization: Bearer alm_live_... (note the space after "Bearer")
  • Check for trailing whitespace or newline characters in your key
  • Make sure you are not using a revoked or rotated key

Getting 400 on chart endpoints?

  • Date format must be YYYY-MM-DD
  • Time format must be HH:MM (24-hour)
  • Latitude must be between -90 and 90, longitude between -180 and 180
  • POST endpoints require Content-Type: application/json

Getting 408 timeouts?

  • Reduce the date range for eclipse and retrograde queries
  • Avoid requesting more than 1 year of data in a single call
  • Consider using paginated endpoints where available

Using the Request ID

Every response—success or error—includes a requestId field. When contacting support about an unexpected error, include this ID so the team can trace the exact request through the system logs.

Related