Skip to main content

Errors and limits

Error format​

Every error is returned as JSON in one format, with a matching HTTP status code:

{
  "status": false,
  "code": 401,
  "message": "Invalid API key"
}
  • status. Always false for an error, and true for a successful response.
  • code. The HTTP status code, repeated in the body.
  • message. A short description of what went wrong.

Check the HTTP status code first. The message text is meant for people and can change, so do not match on its exact wording.

Status codes​

200 OK​

The request succeeded. The body has "status": true and a data field.

400 Bad request​

A query parameter has a value the API cannot use. The message names the parameter. For example:

{
  "status": false,
  "code": 400,
  "message": "'limit' must be between 1 and 200"
}

Causes include a limit or offset outside its range, a view other than summary or full, a date that cannot be read, and an updated_since that is not earlier than updated_until. See Lists and syncing.

401 Unauthorized​

The API key is missing or is not accepted.

  • Missing API key. No key was sent in the Authorization header.
  • Invalid API key. The key is unknown, was revoked or replaced, or belongs to a user who is no longer active.

See Authentication and base URL.

403 Forbidden​

The key is valid, and the account has no active subscription:

{
  "status": false,
  "code": 403,
  "message": "This account has no active subscription."
}

This is returned when the subscription has ended, been cancelled, or been frozen. The same key works again once the subscription is active. There is no need to create a new key.

404 Not found​

The record does not exist, or the URL is not an API endpoint.

{
  "status": false,
  "code": 404,
  "message": "Recipe not found"
}

A record that belongs to another account also returns 404. The API gives the same answer for "does not exist" and "is not yours".

405 Method not allowed​

The API is read-only. A POST, PUT, PATCH, or DELETE request to any endpoint returns 405.

429 Too many requests​

The daily request limit was reached. See the next section.

500 Internal error​

Something went wrong on the server. The message is Internal error. Retry after a short wait, and contact support@axxya.com if it continues.

Daily request limit​

Each user can make 500 requests per day with their API key. The count resets at midnight UTC for everyone, whatever your time zone.

Every request made with a valid key counts toward the limit, including requests that return 400 or 404. Requests refused with 401 or 403 do not count. Requests refused with 429 also count, so retrying straight away does not help.

The limit belongs to the user who created the key. Each user on your account who creates their own key has their own 500 requests.

See how many requests you have left​

The API Key card on the Settings page shows how many requests you have made today, for example "Used today: 120 of 500 requests. Resets at midnight UTC."

Your integration can read the same numbers from the response headers.

Rate limit headers​

Responses to requests made with a valid key carry three headers:

  • X-RateLimit-Limit. The daily limit for your key.
  • X-RateLimit-Remaining. How many requests are left today.
  • X-RateLimit-Reset. When the count resets, as Unix time in seconds (the next midnight UTC).
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1792972800

When the limit is reached​

Further requests return 429 until the count resets. The message says what the limit is and when it resets, and the body also carries those values in fields your integration can read:

{
  "status": false,
  "code": 429,
  "message": "Daily request limit reached. This API key's user has made all 500 customer API requests allowed per day. The limit resets at midnight UTC (2026-10-26T00:00:00Z), in 3 hours 12 minutes.",
  "limit": 500,
  "reset_at": "2026-10-26T00:00:00Z",
  "retry_after_seconds": 11520
}
  • limit. The daily limit for your key.
  • reset_at. When the count resets, in ISO 8601 format (UTC).
  • retry_after_seconds. The number of seconds until the count resets.

A 429 response also has a Retry-After header with the number of seconds until midnight UTC:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792972800
Retry-After: 11520

Wait that long before sending more requests.

Staying within the limit​

  • Request pages of up to 200 records instead of reading records one at a time. At 200 records per page, 500 requests can read up to 100,000 records a day.
  • Use view=full on the recipe lists to get full detail without a request for each recipe.
  • Use updated_since to read only what changed since your last sync.
  • Store the ingredients you have read. An ingredient used by many recipes needs to be read once.
  • Check X-RateLimit-Remaining and slow down before it reaches zero.

If your integration needs a higher limit, contact support@axxya.com.