Errors Every error code the API returns, with status, meaning and the fix.
Errors always use real HTTP status codes and a structured body:
{ "success" : false , "error" : "INVALID_DATE" , "message" : "Date must be ISO 8601 format: 1990-01-15T10:30:00" } error is a stable machine-readable code — branch on it, not on message (messages may be reworded; codes will not).
Code Status Meaning MISSING_API_KEY401 No key in X-API-Key or Authorization: Bearer INVALID_API_KEY401 Key unknown or revoked KEY_EXPIRED403 Non-trial key past its expiry date IP_NOT_ALLOWED403 Key is IP-restricted and this request came from elsewhere
Code Status Meaning TRIAL_EXPIRED402 Trial cap (5,000 requests) or 14-day window hit — hard stop QUOTA_EXCEEDED429 Monthly allowance exhausted RATE_LIMITED429 Per-second ceiling hit — retry after Retry-After seconds
Code Status Meaning MISSING_FIELDS400 A required field (date, lat, lng, …) is absent INVALID_DATE400 Date is not ISO 8601 (1990-01-15T10:30:00) INVALID_LATITUDE400 Latitude outside −90…90 INVALID_LONGITUDE400 Longitude outside −180…180 INVALID_ID400 Malformed resource id (e.g. city id on /geo/city) INVALID_BATCH400 /batch body malformed or requests emptyBATCH_TOO_LARGE400 More than 50 items in one batch NESTED_BATCH400 A batch item targeting /batch
Code Status Meaning NOT_FOUND404 No such endpoint or resource NOT_AVAILABLE404 Endpoint exists but is not offered on your channel (e.g. /batch is direct-API only, not available via marketplace resellers)
Code Status Meaning CALCULATION_ERROR422 Input was valid but the ephemeris computation could not complete INTERNAL_ERROR500 Our fault — safe to retry; contact us if it persists
Inside a /batch response, each item carries its own { status, body } envelope — a failing item reports its own error from the tables above without failing the batch. See Batch & field filtering .