Get started

Errors

Every failure carries error.code and error.message. 422 and 429 also follow RFC 9457 problem details.

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your search wallet does not hold enough credits for this request."
  }
}

HTTP status and codes

HTTP	error.code	When
400	`invalid_body` `too_many` `invalid_idempotency_key` `invalid_otp`	Malformed request, more than 25 searches in a batch, or a bad idempotency key or OTP.
401	`unauthorized`	Missing, unknown or deactivated key. See Authentication.
402	`insufficient_credits`	The whole request is refused and nothing is charged.
404	`not_found` `unknown_dim` `unsupported_state`	No such search, lookup or state.
409	`already_finished` `not_waiting` `not_finished` `already_recovery` `idempotency_key_reused`	The search is not in a state that allows this call.
410	`withheld`	A document failed its integrity check and is not served.
422	`invalid_params` `search_unavailable`	The parameters cannot be answered, or the search is held. Nothing is charged.
429	`rate_limited` `too_many_open_searches` `upstream_busy`	Slow down. Honour Retry-After.
502 / 503	`assist_failed` `recovery_failed` `recovery_unavailable` `place_search_unavailable`	An optional layer or a lookup could not answer. Retry later.
500	`internal`	Unexpected. Safe to retry, then contact us.

422 invalid_params

We check your parameters before anything is charged or sent to a source. Every problem is listed, with the field, what you sent and why it was refused. When the field is a place or office, lookup names thelookup that resolves it.

json

{
  "type": "https://legiscore.in/docs/errors#invalid-params",
  "title": "Unprocessable search parameters",
  "status": 422,
  "detail": "sro_code 9999 is not a registered office for telangana.",
  "invalid_params": [
    {
      "index": 0,
      "field": "sro",
      "value": "9999",
      "reason": "sro_code 9999 is not a registered office for telangana.",
      "lookup": "sro"
    }
  ],
  "error": { "code": "invalid_params", "message": "sro_code 9999 is not a registered office for telangana." }
}

422 search_unavailable

The search is held at the moment (shown as HELD on its page). It is refused at submit, before any charge. Check the catalog for current status.

429 too many requests

Three independent limits, all answered the same way, so you need one retry path. The response has Retry-After (seconds) and X-RateLimit-Limit / X-RateLimit-Remaining.

Limit	Default	Applies to
Submit	120 searches per minute per key. A batch of 25 spends 25.	POST /api/v1/search
Reads	10 times the submit budget per key	GET search and list
Open searches	100 queued or running per workspace	POST /api/v1/search
Lookups	120 calls per minute per key	GET lookups and places

json

{
  "type": "https://legiscore.in/docs/errors#too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit reached: 120 per minute for this key. Retry after 12s.",
  "retry_after": 12,
  "error": { "code": "rate_limited", "message": "Rate limit reached: 120 per minute for this key. Retry after 12s." }
}

upstream_busy means the search service is at capacity. Nothing was charged. Retry after the interval given. In a batch, an item refused this way appears in rejected[] with its own retry_after.

HTTP status and codes

HTTP	error.code	When
400	`invalid_body` `too_many` `invalid_idempotency_key` `invalid_otp`	Malformed request, more than 25 searches in a batch, or a bad idempotency key or OTP.
401	`unauthorized`	Missing, unknown or deactivated key. See Authentication.
402	`insufficient_credits`	The whole request is refused and nothing is charged.
404	`not_found` `unknown_dim` `unsupported_state`	No such search, lookup or state.
409	`already_finished` `not_waiting` `not_finished` `already_recovery` `idempotency_key_reused`	The search is not in a state that allows this call.
410	`withheld`	A document failed its integrity check and is not served.
422	`invalid_params` `search_unavailable`	The parameters cannot be answered, or the search is held. Nothing is charged.
429	`rate_limited` `too_many_open_searches` `upstream_busy`	Slow down. Honour Retry-After.
502 / 503	`assist_failed` `recovery_failed` `recovery_unavailable` `place_search_unavailable`	An optional layer or a lookup could not answer. Retry later.
500	`internal`	Unexpected. Safe to retry, then contact us.

422 invalid_params

json

{
  "type": "https://legiscore.in/docs/errors#invalid-params",
  "title": "Unprocessable search parameters",
  "status": 422,
  "detail": "sro_code 9999 is not a registered office for telangana.",
  "invalid_params": [
    {
      "index": 0,
      "field": "sro",
      "value": "9999",
      "reason": "sro_code 9999 is not a registered office for telangana.",
      "lookup": "sro"
    }
  ],
  "error": { "code": "invalid_params", "message": "sro_code 9999 is not a registered office for telangana." }
}

422 search_unavailable

The search is held at the moment (shown as HELD on its page). It is refused at submit, before any charge. Check the catalog for current status.

429 too many requests

Three independent limits, all answered the same way, so you need one retry path. The response has Retry-After (seconds) and X-RateLimit-Limit / X-RateLimit-Remaining.

Limit	Default	Applies to
Submit	120 searches per minute per key. A batch of 25 spends 25.	POST /api/v1/search
Reads	10 times the submit budget per key	GET search and list
Open searches	100 queued or running per workspace	POST /api/v1/search
Lookups	120 calls per minute per key	GET lookups and places

json

{
  "type": "https://legiscore.in/docs/errors#too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit reached: 120 per minute for this key. Retry after 12s.",
  "retry_after": 12,
  "error": { "code": "rate_limited", "message": "Rate limit reached: 120 per minute for this key. Retry after 12s." }
}

upstream_busy means the search service is at capacity. Nothing was charged. Retry after the interval given. In a batch, an item refused this way appears in rejected[] with its own retry_after.