New Numerology API
Docs menu
Download

API errors and how to handle them

Updated

Every error from API for Astrology (apiforastrology.com) comes back as JSON with an HTTP status code. The body holds a short code, a plain message and, for a bad input, the field. Fix the request after a 4xx status. Retry only a 429 or a 5xx, after the Retry-After wait. Failed calls never count toward your plan.

Error shape

Every error comes back as JSON in the same shape:

{
  "error": {
    "code": "invalid_input",
    "message": "The birth date must be between January 1, 1850 and December 31, 2149.",
    "field": "year"
  }
}
  • code: a short code for your program to check. Codes do not change. A new code is listed in the changelog.
  • message: what went wrong, in plain English. The wording can change, so show it or log it, but do not match on it.
  • field: the request field that caused the error, when one field did.

Every response also has an X-Request-Id header. Include it when you contact support about a request.

The Numerology API sends the same errors in the same shape. For example, a name in another script gets invalid_input with field set to name. Its own changes are in the numerology changelog.

The Errors tab on your Usage page shows your failed requests by type, and how to fix each one. It also lists each failed request from the last 90 days, with its request ID and the response we sent.

Status codes

StatusCodeWhat it means and what to do
400invalid_json, bad_requestThe request body is not valid JSON, or the API could not read it. For example, the connection closed while it was being sent. Check the body you send.
401unauthorizedThe API key is missing, mistyped or unknown. Send a valid key. See how to send your key.
401key_disabledThe key is paused, by your team, by us, or because we found it in public code. An owner or admin can enable it on the API keys page. Or they can roll it to get a new key.
401key_expiredThe key was rolled more than 24 hours ago. Use the new key from the API keys page.
401key_revokedThe key was revoked and can never work again. Create a new key on the API keys page.
403account_suspendedThe account that owns the key is suspended, so none of its keys work. Do not retry. If you think we made a mistake, reply to the email we sent within 30 days. We will review it.
403sample_charts_onlyA test key asked for a written reading on a chart that is not a sample chart. The sample charts are John Doe, New York, and Jane Doe, Chicago. Or the test key asked for a date other than today or the date in the docs examples. Use a live key, or send a sample chart. See test keys.
404not_foundThe path does not exist, or a name in it is unknown (for example a festival). The message lists the names you can use.
405method_not_allowedWrong HTTP method for this path. The Allow header lists the right one.
413payload_too_largeThe request body is larger than 64 KB.
422invalid_input, no_sunrise, window_too_wide, language_not_availableA field is missing or out of range, such as a year before 1850 (see supported dates). The field property names it. The API also refuses a local time that happens twice, when clocks go back: send timezone_fold as 0 or 1 (see times and time zones). no_sunrise: the Sun does not rise at that place on that date (far north or south). window_too_wide: the date range is too long; ask for a shorter one. language_not_available: the lang value is not a language the API answers in; the message lists the ones it does.
429rate_limited, quota_exceeded, reading_credits_exceeded, test_quota_exceededYou hit one of four limits. This key made too many calls this minute. Or your live keys used up the monthly calls. Or a written reading needs more reading credits than are left this month. Or your test keys used up their monthly test calls. Wait for Retry-After seconds, or move to a bigger plan in Billing. See rate limits and quotas.
500, 502, 503, 504server_error, bad_gateway, unavailable, timeoutA temporary problem on our side. Retry after a short wait.

When to retry

  • 429: wait the number of seconds in Retry-After, then retry.
  • 500, 502, 503 and 504: retry after a short wait. Wait longer after each failure, for example 1, 2, then 4 seconds.
  • Any other 4xx: do not retry. Fix the request first. The same request will fail the same way.

The 429 status and the Retry-After header are standard HTTP. 429 is defined in RFC 6585, and Retry-After in RFC 9110. So most HTTP clients can read them for you. Here is the same rule in plain JavaScript:

JavaScript
// Sends a request again after a 429 or a 5xx answer, up to 3 tries.
// It waits as long as Retry-After says, or 1 second, then 2 seconds.
async function fetchWithRetry(url, options) {
  const maxTries = 3;
  for (let tryNumber = 1; tryNumber <= maxTries; tryNumber++) {
    const res = await fetch(url, options);
    const canRetry = res.status === 429 || res.status >= 500;
    if (!canRetry || tryNumber === maxTries) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? 0);
    // A monthly limit says to wait until next month. Stop instead.
    if (retryAfter > 60) return res;

    const waitSeconds = retryAfter || 2 ** (tryNumber - 1);
    await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
  }
}

Every endpoint lists its responses in the API reference.

Next steps

From the blog