API

Errors & Rate Limits

Handle Qorlivo API error responses, HTTP status codes, validation messages, plan gates, conflicts, and retry headers.

The Qorlivo API uses standard HTTP status codes and JSON error bodies. Your integration should handle expected errors instead of treating every non-2xx response as an unknown failure.

Error shape

Most errors use this shape:

{
  "error": {
    "message": "Missing required field: url",
    "code": 400
  }
}

Bulk link creation returns per-item statuses inside a results array. See Links API.

Status codes

Status	Meaning	Common fix
`400`	Invalid request body or query parameter.	Check JSON shape, required fields, URLs, dates, and limits.
`401`	Missing, malformed, expired, or invalid API key.	Send a valid Bearer key.
`403`	Plan does not include the action or the resource is not allowed.	Upgrade or use an allowed action.
`404`	Resource was not found for this account.	Confirm the ID belongs to the authenticated workspace.
`409`	Conflict, usually a slug already exists.	Use a different slug or generated slug.
`429`	Rate limit exceeded.	Wait and retry after the provided delay.
`503`	Authentication service temporarily unavailable.	Retry with backoff.

Validation examples

Invalid URL:

{
  "error": {
    "message": "url must be a valid http or https URL",
    "code": 400
  }
}

Read-only plan attempting a write:

{
  "error": {
    "message": "Tier 'free' is read-only. Upgrade to Creator or higher for write access.",
    "code": 403
  }
}

Bulk API on an unsupported plan:

{
  "error": {
    "message": "Bulk link creation requires the Business plan. Current tier: 'pro'.",
    "code": 403
  }
}

Rate-limit headers

Rate-limited responses include retry information.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783027439000
Retry-After: 17

Use Retry-After when present. It is the number of seconds to wait before retrying.

Retry guidance

Response	Retry?	Notes
`400`	No	Fix the request first.
`401`	No	Replace or send the correct key.
`403`	No	Change plan or requested action.
`404`	Usually no	Confirm the ID and account.
`409`	No	Choose a different slug or resolve the conflict.
`429`	Yes	Wait for `Retry-After`.
`503`	Yes	Use exponential backoff.

Idempotency advice

For create-heavy automations:

Choose deterministic slugs when safe.
Store returned resource IDs.
Treat 409 as a signal to fetch or choose a new slug.
Avoid retrying a successful create if the network failed after Qorlivo responded.
Use bulk creation only when your workflow can handle partial success.