Errors

Biqli uses HTTP status codes for the broad result and stable error codes for programmatic handling. Error messages are written for people and may become more specific over time; integrations should branch on error.code.

Error response

API errors use one JSON envelope:

{
  "error": {
    "code": "validation_error",
    "message": "The long url field is required.",
    "details": {
      "errors": {
        "long_url": [
          "The long url field is required."
        ]
      }
    }
  },
  "request_id": "ae437f49-30a3-4d55-bca6-dc523f2efcb3"
}

Field	Type	Description
`error.code`	string	Stable machine-readable error identifier.
`error.message`	string	Human-readable explanation of this failure.
`error.details`	object	Optional structured context, such as field errors or a required permission.
`request_id`	string	Identifier for tracing the request with Biqli support.

Do not assume details is always present. Ignore unrecognized detail fields so Biqli can add useful context without breaking your integration.

Error catalog

Authentication and access

Status	Code	Meaning	Action
`401`	`invalid_token`	The API key is missing, malformed, invalid, or revoked.	Replace or correct the key.
`403`	`insufficient_scope`	The key or its creator lacks a required permission.	Grant the permission shown in `details.required_permission`, when present.
`403`	`upgrade_required`	The workspace plan does not include the requested capability.	Review the plan information in `details` or remove the restricted feature.
`403`	`quota_exceeded`	A plan resource quota, such as the number of links, has been reached.	Remove unused resources or increase the workspace allowance.

Read Authentication for workspace scope and permission dependencies.

Resources and conflicts

Status	Code	Meaning
`404`	`resource_not_found`	The resource or pagination cursor is unavailable in the key’s workspace.
`409`	`domain_taken`	The domain is connected to another Biqli account.
`409`	`alias_taken`	The alias is already in use on the selected domain.
`409`	`external_id_taken`	The external ID is already in use in the workspace.
`409`	`folder_name_taken`	A folder already uses that name in the workspace.
`409`	`tag_name_taken`	A tag already uses that name in the workspace.
`409`	`pixel_name_taken`	A tracking pixel already uses that name in the workspace.
`409`	`biolink_name_taken`	A Biolink already uses that name in the workspace.

Biqli intentionally returns the same resource_not_found response for a missing resource and a resource belonging to another workspace.

Request and validation failures

Status	Code	Meaning
`405`	`method_not_allowed`	The endpoint does not support the requested HTTP method.
`422`	`validation_error`	One or more body, query, or cursor values are invalid or unsupported.
`422`	`url_blocked`	URL safety rules rejected one or more destination fields.
`422`	`dns_verification_failed`	The required DNS records are missing or have not propagated.

Unknown JSON fields are rejected instead of silently ignored. For a validation failure, details.errors maps each invalid field to one or more explanations:

{
  "error": {
    "code": "validation_error",
    "message": "The active field must be true or false.",
    "details": {
      "errors": {
        "active": ["The active field must be true or false."],
        "widget_data": ["The widget_data field is not supported by this endpoint."]
      }
    }
  },
  "request_id": "ae437f49-30a3-4d55-bca6-dc523f2efcb3"
}

Correct every reported field before retrying.

Throttling and server failures

Status	Code	Meaning	Action
`429`	`rate_limit_exceeded`	The workspace exhausted its current request allowance.	Honor `Retry-After`, then retry.
`500`	`internal_server_error`	Biqli could not complete the request because of an unexpected failure.	Retry with backoff; contact support if it persists.

Read Rate limits before implementing 429 retries.

Request tracing

Every API error includes the same identifier in:

X-Biq-Request-Id: ae437f49-30a3-4d55-bca6-dc523f2efcb3

{
  "request_id": "ae437f49-30a3-4d55-bca6-dc523f2efcb3"
}

You may send your own non-empty X-Biq-Request-Id value of up to 100 characters. Use a unique value per logical request and include it in your logs. Do not place API keys, passwords, URLs containing secrets, or personal data in the request identifier.

Retry decisions

Result	Retry?	Recommended behavior
Network interruption	Sometimes	Retry with exponential backoff and jitter. Use `external_id` where supported to avoid duplicate creates.
`401`, `403`	No	Correct credentials, permissions, plan access, or resource quota first.
`404`	No	Verify the resource ID, workspace, filters, and cursor.
`405`, `409`, `422`	No	Correct the request before retrying.
`429`	Yes	Wait for `Retry-After`; it takes precedence over other timing hints.
`500`	Yes	Use capped exponential backoff with jitter and a maximum attempt count.

Never retry indefinitely. Preserve the original X-Biq-Request-Id for retries of the same logical operation, or record both the original and replacement IDs in your trace.

Bulk endpoint failures

Bulk create and bulk update can return 207 Multi-Status. This is a completed HTTP request, but one or more items failed. Always inspect every ordered results item and the summary object:

{
  "results": [
    {
      "index": 0,
      "status": "success",
      "link": {
        "id": "biq_lnk_01M14D2M8VFKYQCE7Z3A6HRXWP"
      }
    },
    {
      "index": 1,
      "status": "error",
      "error": {
        "code": "validation_error",
        "message": "The long url field is required.",
        "details": {
          "errors": {
            "long_url": ["The long url field is required."]
          }
        }
      }
    }
  ],
  "summary": {
    "requested_count": 2,
    "created_count": 1,
    "failed_count": 1
  },
  "status": "partial_success"
}

Retry only the failed items after correcting their errors. Do not assume that every 2xx response means every requested bulk operation succeeded.

GETTING STARTED

BIQLI LINKS API

Error response

Error catalog

Authentication and access

Resources and conflicts

Request and validation failures

Throttling and server failures

Request tracing

Retry decisions

Bulk endpoint failures

​Error response

​Error catalog

​Authentication and access

​Resources and conflicts

​Request and validation failures

​Throttling and server failures

​Request tracing

​Retry decisions

​Bulk endpoint failures

Error response

Error catalog

Authentication and access

Resources and conflicts

Request and validation failures

Throttling and server failures

Request tracing

Retry decisions

Bulk endpoint failures