Errors

HTTP status codes, common error responses, and how to fix them

Status codes

Code	Meaning
200	Success. The request completed as expected.
400	Bad request. The request body is malformed or missing required fields.
401	Unauthorized. The x-token header is missing or the API key is invalid.
403	Forbidden. The API key does not have permission to access this resource.
404	Not found. The board ID, card ID, or contact ID does not exist.
429	Too many requests. You have exceeded the rate limit.
500	Internal server error. Something went wrong on the Aptly side.

---

Frequent errors

Missing x-token header

Be sure to include the header x-token: YOUR_API_KEY on every request.

{
  "error": "Unauthorized"
}

Fix: Copy your API key from Card Sources > API in the Aptly UI and pass it as the x-token header.

---

Wrong API key for the board

Each board generates its own API key. Using a key from one board against a different board’s endpoint will fail.

{
  "error": "Unauthorized"
}

Fix: Confirm that the API key you are using was generated for the specific board ID in your request URL. Both are visible together in Card Sources > API.

---

Board ID does not exist

The board ID in the URL does not match any board associated with your API key.

{
  "error": "Not found"
}

Fix: Double-check the board ID in your request URL against the POST URL shown in Card Sources > API. A common cause is copying the board ID from one environment and using it with credentials from another.

---

Malformed request body

The request body could not be parsed as valid JSON, or the Content-Type header is missing.

{
  "error": "Bad request"
}

Fix: Ensure your request includes -H "Content-Type: application/json" and that the body is valid JSON. Run your payload through a JSON validator if you are unsure.

---

Card ID not found

The card ID passed in the URL does not exist or has been deleted.

{
  "error": "Not found"
}

Fix: Retrieve a fresh list of cards from the board to confirm the card still exists before attempting to fetch or update it.

---

Rate limit exceeded

You have sent too many requests in a short period.

{
  "error": "Too many requests"
}

Fix: Slow down your request rate and retry after a short delay. If you are paginating through a large board, add a small pause between page requests.

---

Server error

Something went wrong on Aptly’s side. These are rare.

{
  "error": "Internal server error"
}

Fix: Retry the request after a brief wait. If the error persists, contact Aptly support at [e-mail] with the request details and timestamp.