Error codes reference

Complete reference of asicapi error codes with HTTP statuses, the ASIC rejection codes they map to, what each one means and how to fix it in your integration.

asicapi uses one error envelope for every failure, from a malformed ACN to an ASIC outage. Each error has a stable code you can branch on, an HTTP status that follows the usual REST meaning, a human-readable message, and where the failure originated at ASIC the original ASIC rejection code so you can cross-reference ASIC's own documentation. Every code on this page can be linked directly as https://asicapi.dev/docs/errors#code, which is exactly what the docUrl field in the error points at.

The error object

Response (400 Bad Request)

{
  "error": {
    "type": "invalid_request_error",
    "code": "acn_invalid",
    "message": "The ACN 004085617 fails the ASIC check digit test.",
    "param": "id",
    "asicCode": "CE01",
    "requestId": "req_01J8ZK3V7Q0M2X",
    "docUrl": "https://asicapi.dev/docs/errors#acn_invalid"
  }
}

Field	Type	Description
`type`	string	Broad category, one of the types below. Useful for generic handling (retry, re-authenticate, fix the request)
`code`	string	Specific, stable error code. Branch on this
`message`	string	Plain-English explanation intended for developers. Wording may change; do not parse it
`param`	string or null	The path, query or body parameter the error relates to, when there is one
`asicCode`	string or null	The ASIC rejection code that caused the error, when the request was rejected by ASIC. Codes ending 01 to 49 are request validation failures; 50 to 99 relate to the availability of ASIC data
`requestId`	string	Same value as the `X-Request-Id` header. Quote it to support
`details`	object	Present on some errors with structured extra information, for example `counts` on `no_matches` and `too_many_matches`, or `purchase` on `extract_required`
`docUrl`	string	Link to the matching row on this page

Error types and HTTP statuses

Type	HTTP status	Meaning	Retry?
`invalid_request_error`	400, 410, 422	The request is malformed, refers to something that no longer exists, or asks ASIC for something it cannot supply for this record	No, fix the request
`authentication_error`	401	Missing, malformed or revoked API key	No
`extract_required_error`	402	A section endpoint was called for data that only exists in an extract you do not hold. `details.purchase` is the request that would buy it	After purchasing the extract
`permission_error`	403	The key is valid but not allowed to do this: product not enabled, wrong jurisdiction, or a resource owned by another account	No
`not_found_error`	404	The company, person, document, order or register entry does not exist, or a search found nothing	No
`conflict_error`	409	An idempotency key was reused with a different body	No
`rate_limit_error`	429	Too many requests or too many concurrent requests	Yes, after `Retry-After`
`asic_unavailable_error`	503	ASIC's database is unavailable or in a maintenance window	Yes, with backoff
`api_error`	500, 502	asicapi or ASIC application failure	Yes, once, then contact support

Universal errors

Returned by any endpoint that talks to ASIC.

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`product_unavailable_in_jurisdiction`	403	ZZ01	ASIC does not offer this product for the requested jurisdiction. Victorian business names are the common case	Use jurisdiction `ASIC` or a jurisdiction that offers the product
`product_not_enabled`	403	ZZ02	Your account has not enabled this product, or has not enabled it for the requested jurisdiction	Enable the product or jurisdiction in the dashboard
`asic_unavailable`	503	ZZ51	ASIC's database is not available. Typically a scheduled maintenance window	Retry with exponential backoff; honour `Retry-After`. See rate limits
`asic_application_error`	502	ZZ53	ASIC's application rejected the request with an internal error	Retry once. If it persists, contact support with the `requestId`
`sandbox_product_unavailable`	403	ZZ54	A test key asked for a product ASIC's sample client does not serve (weekly summaries)	Use a live key for this product

Company errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`acn_invalid`	400	CE01, CD01, CR01, CC01	The ACN, ARBN or ARSN is not nine digits or fails the check digit test	Validate with `GET /v1/identifiers/{value}` before calling
`company_not_found`	404	CE03, CD07, CR03	No organisation with this ACN, ARBN, ARSN or ASIC identifier exists on the register	Confirm the number with a name search
`abn_and_acn_supplied`	400	CE04	Both an ABN and an ACN were supplied for one lookup	Send one identifier
`abn_invalid`	400	CE10	The 11-digit ABN fails the ABN check digit test	Check the ABN
`abn_not_acn_based`	400	CE11	The ABN is valid but does not embed an ACN, so it belongs to a sole trader, partnership or trust rather than a company	Search by name, or look the entity up on the ABR
`abn_not_found`	404	CE12, CE13	The company matching the ACN has no ABN recorded, or no company matches the ACN contained in the ABN	Look up by ACN instead
`extract_unavailable_for_type`	422	CE51, CR51, CC51	The organisation type has no extract product. Company extracts exist for proprietary and public companies, registered bodies, foreign companies and managed investment schemes; a purchase for a business name, name reservation or other organisation type is refused	Look the organisation up with the free endpoints instead; nothing is charged
`no_relational_data`	404	CR02	The company holds no roles, licences or shareholdings in other organisations	Treat as an empty result
`document_period_conflict`	400	CD02	Both `years` and a `from`/`to` date range were supplied	Send one or the other
`document_date_range_invalid`	400	CD03, CD04	`from` was given without `to`, or `from` is later than `to`	Fix the range
`identifier_conflict`	400	CD05, CD06	More than one of ABN, organisation number or jurisdiction/state number was supplied, or a state number was supplied without a jurisdiction	Send one identifier; add `jurisdiction` for state registration numbers
`business_name_not_found`	404	CD08, CD09	The business registration number does not exist in this jurisdiction, or ASIC has no details for it	Check the number and jurisdiction from the search result
`document_list_unavailable`	422	CD51	ASIC does not hold a document list for this organisation (business names and name reservations)	Not applicable to this organisation type
`no_charges`	404	CC52	No charges match the request for this company	Treat as an empty result
`charge_not_found`	404	CH01	The charge number is invalid or does not exist	Take charge numbers from the company's charges list

Search errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`search_scope_invalid`	400	ON02	The `scope` value is not one of the documented scopes	Use a value from the name search scope table
`no_matches`	404	ON51, PN51, RP51, RR51, RB51, RQ51, RS51, RC51	The search found nothing, or found names that were all rejected by your criteria. `details.counts` says which	Broaden the search or lower `minScore`. If `found` is non-zero there are matches you filtered out
`too_many_matches`	422	ON52, PN52	More than 100 names matched at the exact or primary key level, or ASIC's people index returned only a fuzzy count	Add words, set `exact=true`, narrow `scope`, add a date of birth range, or use the offline search. See pagination
`name_required`	400	PN01, PN02	`familyName` or `givenName` is missing from a people search	Supply both
`name_invalid_characters`	400	PN03	A name contains digits, full stops, commas or other characters outside letters, hyphens, apostrophes and spaces	Strip punctuation and numerals
`birth_date_range_invalid`	400	PN05, PN06, PN07	`birthDateFrom` without `birthDateTo`, a start date in the future, or a start date after the end date	Fix the range

Example: no_matches with counts

Response (404 Not Found)

{
  "error": {
    "type": "not_found_error",
    "code": "no_matches",
    "message": "No names matched \"ACME WIDGETS\" with minScore=95. ASIC found 37 candidate names that were excluded by your criteria.",
    "param": "q",
    "asicCode": "ON51",
    "requestId": "req_01J8ZKF5G0H4J8",
    "details": {
      "counts": { "returned": 0, "found": 37 }
    },
    "docUrl": "https://asicapi.dev/docs/errors#no_matches"
  }
}

counts.returned is the number of names ASIC would have returned and counts.found is the total ASIC located before applying your criteria. Both are zero when nothing at all matched.

Extract errors

Raised by the section endpoints that read from a purchased extract, by GET /v1/extracts/{id}, and by the extract query parameter. The buy-then-read sequence is explained on free lookups, extracts and orders. asicCode is null on all of them because the extract store is asicapi's, not ASIC's.

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`extract_required`	402	none	You hold no extract that contains the requested section, or you hold a current extract but asked for ceased records, charges, annual returns or financial reports, which need a historical one. `details.purchase` is the exact request that would satisfy the call	Make the purchase in `details.purchase` (`POST /v1/companies/{id}/extracts`, `POST /v1/people/extracts` or the register equivalent) and retry
`extract_not_found`	404	none	No extract with this id exists	Check the id; list what you hold with `GET /v1/extracts`
`extract_expired`	410	none	The extract is older than 12 months and is no longer stored	Purchase a new extract
`extract_owner_mismatch`	403	none	The extract belongs to a different account or environment. Sandbox and live extracts are not interchangeable	Use your own extract ids
`extract_type_invalid`	400	RS02	`type` on a purchase is not `current`, `historical` or `relational`, `history` is not a boolean, or the `extract` query parameter names an extract of a different kind than the endpoint serves (for example a person extract on a company section)	Fix the body or pass an extract of the right kind

Example: extract_required with the purchase to make

Response (402 Payment Required)

{
  "error": {
    "type": "extract_required_error",
    "code": "extract_required",
    "message": "Office holders are part of a company extract. Purchase one with POST /v1/companies/004085616/extracts.",
    "param": null,
    "asicCode": null,
    "requestId": "req_01J9AB3K7Q2XM4",
    "docUrl": "https://asicapi.dev/docs/errors#extract_required",
    "details": {
      "purchase": {
        "method": "POST",
        "path": "/v1/companies/004085616/extracts",
        "body": { "type": "current" },
        "product": "company_extract_current"
      }
    }
  }
}

details.purchase.body is { "type": "historical" } when the request needs a historical extract, and details.purchase.product names the scope the purchase will consume so you can check it against your key before spending. A 402 never incurs a fee.

People errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`search_expired`	410	PE01, PD01	The `searchId` or person id refers to a people search older than 30 days, which ASIC no longer retains	Run the search again and use the new ids
`search_owner_mismatch`	403	PE02, PD02	The person id was produced by a search from a different account or environment	Use ids from your own searches; test and live ids are not interchangeable
`person_not_found`	404	PE03, PD03	The person id does not exist in the referenced search	Check the id against the search results
`person_too_many_roles`	422	PE51	The person has more than 999 roles and ASIC will not produce the extract online	Contact support; ASIC handles these extracts by arrangement

Document errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`document_number_invalid`	400	DD01, DI01	The document number is not nine characters starting with a digit	Take document numbers from a document list
`duplicate_document_number`	400	DD02, DI07	The same document number appears twice in one request	Deduplicate `numbers[]`
`document_not_found`	404	DD51, DI51	No document with this number exists	Check the number
`document_not_imaged`	422	DD52, DI52	The document exists but is not in ASIC's imaging system, so no image can be ordered. `imaged` is `false` on the document	Nothing can be ordered online
`page_range_invalid`	400	DI02, DI08, DI53	`pages.to` is less than `pages.from`, only one of them was given, or the document does not contain the requested pages	Check `pageCount` on the document
`delivery_invalid`	400	DI03, DI04, DI05, DI06, CC03, CC04, CC05, CC06	`delivery.method` is not `web`, `email` or `post`, or the instructions for that method are incomplete (missing email, missing postal details)	Fix the `delivery` object
`document_too_large_for_delivery`	422	DI54, DI55, DI56, DI57, CC53, CC54, CC55, CC56	The document exceeds the size limit for the chosen method: 50 pages for email, 500 pages for web. Over 500 pages must be posted	Choose `web` for up to 500 pages or `post` beyond that

Register errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`register_invalid`	400	RP01, RQ01, RR01, RS01, RB01, RC01	The `{register}` path segment is not a valid register code	Use a code from `GET /v1/registers`
`browse_key_too_short`	400	RP02, RR02, RB02	The `name` browse key is shorter than two characters	Supply at least two characters of the family name

An invalid history value on POST /v1/registers/{register}/entries/{number}/extracts returns extract_type_invalid.

Weekly summary errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`summary_type_invalid`	400	WS01	The `{type}` path segment is not one of the six summary slugs	Use `new-registrations`, `name-changes`, `external-administrations`, `licences-granted`, `disqualified-directors` or `new-schemes`
`week_start_invalid`	400	WS02	`weekStarting` is not a Monday, is not a completed week, or is more than a year ago	Send the Monday of a completed week within the last 12 months
`summary_unavailable`	404	WS51	ASIC has not produced the summary for that week	Try the previous week or retry later in the week
`summary_empty`	200	WS52	No occurrences for that week and type. This is not an error: you receive an empty list with `totalCount: 0`	Nothing to do

Order errors

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`order_not_found`	404	RO51	No order with this id exists, or the continuation token behind it has expired	Check the id; list orders with `GET /v1/orders`
`order_owner_mismatch`	403	RO01	The order belongs to a different account or environment	Use your own order ids
`order_not_ready`	409	none	The download was requested before the order reached `ready`	Poll `GET /v1/orders/{id}` or wait for the `order.ready` webhook
`order_download_expired`	410	none	The download link is older than 7 days	Place a new image order

Platform errors

Raised by asicapi itself before or after talking to ASIC. asicCode is null.

Code	HTTP	ASIC rejection code(s)	Meaning	What to do
`unauthorized`	401	none	Missing, malformed, revoked or expired API key	Send a valid key. See authentication
`rate_limited`	429	none	More than 600 requests in a minute or more than 20 concurrent requests on this key	Wait for `Retry-After` seconds. See rate limits
`validation_error`	422	none	A parameter failed validation in a way not covered by a specific code. `param` names it	Read `message` and fix the parameter
`idempotency_conflict`	409	none	An `Idempotency-Key` was reused within 24 hours with a different request body	Use a new key for a new request

Handling errors in code

Branch on type for generic behaviour and on code for anything specific:

TypeScript

const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (!res.ok) {
  const { error } = await res.json();
  switch (error.type) {
    case 'rate_limit_error':
    case 'asic_unavailable_error':
      return retryLater(Number(res.headers.get('Retry-After') ?? 5));
    case 'authentication_error':
      throw new Error('API key rejected, rotate it');
    case 'extract_required_error':
      return purchaseThenRetry(error.details.purchase);
    default:
      if (error.code === 'no_matches') return [];
      throw new AsicApiError(error);
  }
}