Errors

Every failed call returns the same shape. The HTTP status tells you the kind of failure; the code tells you which one.

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_cnr",
    "message": "A CNR has 16 characters: four letters and twelve digits (for example DLHC010012342024); got 15.",
    "param": "cnr",
    "doc_url": "https://adv.heliosynctech.com/developers/errors#invalid_cnr",
    "request_id": "req_8fK2mQx0Zp3LrT7vWc9aB1dE"
  }
}

• type is one of nine kinds (the table below). Handle a whole kind in one place.
• code is stable and specific. Branch on it, never on message, which is written for people and may change.
• message says how to fix the problem.
• param names the field or header at fault, when one is.
• doc_url opens the section on this page for the code.
• request_id is also in the AOS-Request-Id header. Send it to support if you need help.

A failed call is never billed, and neither is a call that succeeds but finds nothing. Check AOS-Credits-Charged to see what a call cost.

#Types

Type	HTTP	Meaning	Retry?
invalid_request	400	Something in your request is wrong.	No: fix it first.
authentication	401	The key is missing, wrong, revoked or expired.	No.
insufficient_credits	402	Not enough credit, or the day's spend limit.	After topping up, or tomorrow.
permission	403	The key may not do this.	No.
not_found	404	No such case, order, report or route.	No.
conflict	409	The request clashes with the state of something.	Sometimes: see the code.
rate_limited	429	Too many requests.	Yes, after RateLimit-Reset.
upstream_unavailable	503	A court portal or an AI model is down.	Yes, with backoff.
server_error	500	Our fault.	Yes, then tell us the request_id.

Any other 4xx we did not name has the code http_ followed by its status number, such as http_413, and the type invalid_request.

#invalid_request (400)

#method_not_allowed

The path exists but not for this HTTP method. This one answers 405, and the message lists the methods that are allowed.

#invalid_param

A field is missing, or has the wrong type, format or range. param names it and message says what was expected. Dates must be yyyy-MM-dd, limit must be 1 to 100, and amounts are numbers, not text.

#invalid_cnr

The CNR is not four letters and twelve digits, such as DLHC010012342024. Check for spaces, a missing digit or a copied hyphen. Sandbox CNRs look like SBXX010000012026.

#test_mode_live_cnr

You sent a real CNR with a test key. Test keys read only the sandbox. Use a sandbox CNR (SBXX01 + six digits + 2026), or make a live key for real cases.

#live_mode_sandbox_cnr

You sent a sandbox CNR with a live key. Read it with a test key.

#test_mode_live_order

You sent a real order id (ord_…) with a test key. Test keys read only sandbox orders, with ids like sbx_SBXX010000012026_1.

#search_term_required

GET /cases needs at least one of party, advocate or number.

#invalid_cursor

The cursor is not a next_cursor from this list. Start again without a cursor, and never build one yourself. See pagination.

#invalid_after

On GET /events, the after event does not exist in this account and mode. A sandbox reset removes test events. Start again without after.

#invalid_date

A date is not yyyy-MM-dd or is not a real date.

#invalid_dates

The dates of a limitation calculation cannot be right, for example a certified copy ready before it was applied for. param names the one to fix.

#range_too_long

GET /usage was asked for more than 366 days. Ask for a shorter range.

#invalid_sandbox_date

The AOS-Sandbox-Date header is not a date like 2026-12-01.

#unknown_version

The AOS-Version header is not a version we have. Use a date from the changelog, or leave the header out to use your account's pinned version.

#invalid_idempotency_key

An Idempotency-Key has at most 255 characters.

#invalid_court

The court of a judgment search matches nothing. Use sc, hc, or a High Court name such as Delhi.

#invalid_forum

The forum of a tribunal-order search is not one of nclat, nclt, itat, cestat, ngt, cci, cat, aft, aptel or tdsat.

#state_not_supported

Court fee is worked in code for Karnataka, Rajasthan, Kerala, Telangana, Maharashtra and Gujarat only. The message lists them. For another State, enter the fee by hand.

#invalid_act

The act of GET /code-map is not IPC, CrPC, IEA, BNS, BNSS or BSA.

#unknown_rule

The limitation rule is not one we have. Call GET /limitation/rules and use a key from it.

#too_many_citations

A citation check takes at most 200 citations. Split the text.

#name_too_short

A name needs at least one word of 3 letters to be searched.

#invalid_name

A party watch needs a name, not only words like "Ltd" or "M/s".

#due_diligence_needs_company

A due-diligence report is run on a company. Send subject.kind: company and list the people in subject.entities.

#invalid_webhook_url

A webhook endpoint must be an https address on the public internet, in test and live mode. Private, loopback and link-local addresses (localhost, 10.x, 192.168.x, 169.254.x) are refused. For local work, use aos listen; see webhooks.

#invalid_events

The events of a webhook endpoint must be "*" or a list of event types.

#unknown_blueprint

The draft blueprint is not one we have. GET /drafts/blueprints lists the keys.

#missing_fact

A draft needs a fact the blueprint requires. param names it, as facts.{name}.

#too_many_pages

An intelligence call has more than 500 pages. Split the file.

#batch_not_supported

"mode": "batch" works on POST /records/read only.

#answer_withheld

The model's answer was held back because it could not be supported. Nothing was charged. Ask again, more narrowly.

#invalid_request

The workspace refused the input; message says what to change.

#authentication (401)

#missing_api_key

There was no Authorization header. Send Authorization: Bearer aos_test_… or aos_live_….

#invalid_api_key

The key is not one we know. Look for a stray space or newline, a truncated paste, or a key from a different server. Keys are case-sensitive.

#revoked_api_key

The key was revoked in Firm › Developers. Make a new key and update your secret store.

#expired_api_key

The key passed its expiry date. Make a new key.

#insufficient_credits (402)

#insufficient_credits

The allowance, grants and wallet together cannot cover this call. Top up the wallet in Firm › Developers, or move to a plan with included credits. The call did not run and was not billed. See pricing.

#daily_spend_cap

This call would take today's spend over your tier's limit (₹100 for T0). The limit resets at midnight IST, and rises as the account moves up a tier. See rate limits.

#ai_limit

The AI budget for this call was used up. Nothing was charged. Try again later or with less.

#permission (403)

#missing_scope

The key lacks the scope this endpoint needs. message names it. Make a new key with that scope; see authentication.

#paid_account_required

Searching by a party's or person's name is open to accounts that have paid at least once. Top up the wallet or choose a plan, then try again. Searching by CNR or case number needs no payment.

#protected_category

The order belongs to a protected category (POCSO, sexual offences, matrimonial, juvenile), so its PDF is withheld. Its text is withheld too (GET /orders/{id} answers with withheld: true, free). If you hold a takedown or masking order, use the grievance page; we act within 72 hours.

#test_mode_only

The endpoint (/sandbox/*) works with test keys only. Use an aos_test_ key.

#oauth_workspace_only

An OAuth token reaches only the /workspace endpoints. Use an API key for this one.

#read_only_token

The OAuth connection is read-only. The member can allow notes and tasks in Firm › AI & connections.

#connector_off

The firm has switched the MCP connector off, so its OAuth tokens stop.

#write_not_allowed

The member does not have permission to add tasks or notes in the app.

#account_inactive

The firm or member account is switched off. Contact support.

#account_suspended

The firm is paused. Its data is safe; the keys work again once the platform admin lifts the pause.

#feature_off

The developer platform is switched off for this firm's plan.

#forbidden

The key may not do that.

#not_found (404)

#not_found

The path is not an endpoint, or the resource does not exist (a workspace matter, for one). Check the path against the reference.

#case_not_found

No case has this CNR, or, for GET /cases/{cnr}/orders, the case has not been read yet: read it once with GET /cases/{cnr}. Not billed. A record taken down on request also answers this. In the sandbox, SBXX019999992026 always gives this.

#order_not_found

No order has this id. Order ids look like ord_4821 (sbx_… in the sandbox) and come from GET /cases/{cnr}/orders.

#order_pdf_unavailable

The order's PDF is not stored yet. We download a case's PDFs after the case is read; try again in a few minutes. Not billed.

#tribunal_order_not_found

No tribunal order has this id. Ids come from GET /tribunal-orders.

#court_not_found

No court has this code. Call GET /courts for the codes. It answers 404 on every endpoint that takes a court.

#act_not_found

No act has this short name or id. Use IPC, BNS, CrPC, NI and the like, or an act id.

#section_not_found

The act has no such section in the library. Check the section number, including letters such as 438A.

#mapping_not_found

The section has no counterpart in the old and new criminal codes, or it is not mapped yet. Not billed.

#judgment_not_found

No judgment has this id. Ids come from GET /judgments.

#report_not_found

No report has this id on your account and mode. Report ids are private to the account that ordered them, and test keys see test reports only.

#pdf_unavailable

The report has no PDF: it failed, or the PDF could not be laid out. message says which. Order the report again.

#watch_not_found

No watch has this id on your account and mode.

#webhook_endpoint_not_found

No webhook endpoint has this id on your account and mode.

#event_not_found

No event has this id on your account and mode.

#job_not_found

No job has this id on your account and mode. Job ids come from the 202 answer of the call that started it.

#no_material

The library holds nothing on this research question, so there is nothing to answer from. Not billed. Ask about a topic it covers, or drop the court filter.

#conflict (409)

#idempotency_key_reused

You sent an Idempotency-Key you already used for a different request. A key stands for one request. Make a new key; see idempotency.

#idempotency_in_progress

The first request with this Idempotency-Key is still running. Wait a moment and send the same request again.

#report_not_ready

You asked for the PDF of a report that is still queued or running. Wait for the report.completed event, or poll GET /reports/{id}.

#watch_exists

You already watch this case or party. GET /watches finds it.

#too_many_endpoints

An account may have 20 webhook endpoints in each mode. Delete one you no longer use.

#order_not_read

The order's text has not been read yet, so there is nothing to summarise. Fetch it with GET /orders/{id} and ask again.

#rate_limited (429)

#rate_limited

Too many requests a second for your tier. Wait RateLimit-Reset seconds (the Retry-After header says the same) and retry. See rate limits.

#too_many_reports

The account has 100 reports being made. Wait for some to complete (GET /reports), then order more.

#upstream_unavailable (503)

#portal_unavailable

The court's portal did not answer. It is the court's site, not ours, and courts take their portals down often. Not billed. A plain GET /cases/{cnr} falls back to the stored record when there is one, with stale: true; ?fresh=true does not. In the sandbox, SBXX010000042026 always gives this.

#upstream_unavailable

A service we depend on is unavailable just now. Retry in a minute. Not billed.

#ai_unavailable

The AI model could not answer. Not billed. Retry with backoff.

#reader_unavailable

The file could not be read just now. Not billed. Retry, or send a clearer copy.

#server_error (500)

#internal_error

Something broke on our side. It is not billed. Retry once; if it comes back, send us the request_id.