Error Handling

Response Envelope

All v1 API responses use a consistent envelope format:

Success

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "rate_limit": {
      "limit": 1000,
      "remaining": 999,
      "burst_limit": 10,
      "burst_remaining": 9
    }
  }
}

Error

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This endpoint requires the links:write scope.",
    "status": 403
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded
201 Created	Resource created
204 No Content	Resource deleted
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing, invalid, revoked, or expired API key
403 Forbidden	Insufficient scopes or plan feature not available
404 Not Found	Resource does not exist or belongs to another workspace
409 Conflict	Slug already taken or constraint violation
429 Too Many Requests	Rate limit exceeded (burst or monthly)
500 Internal Server Error	Unexpected server error

Common Error Codes

Code	Status	Description
INVALID_API_KEY	401	The API key is malformed or not found
REVOKED_API_KEY	401	The API key has been revoked
EXPIRED_API_KEY	401	The API key has expired
INSUFFICIENT_SCOPE	403	The API key lacks the required scope
FEATURE_NOT_AVAILABLE	403	Your plan does not include this feature
PLAN_LIMIT_EXCEEDED	403	You’ve reached your plan’s resource limit
SLUG_TAKEN	409	The requested custom slug is already in use
RATE_LIMIT_EXCEEDED	429	Monthly API quota exhausted
BURST_LIMIT_EXCEEDED	429	Too many requests per second

Handling Errors

const res = await fetch("https://xqr.co/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

const body = await res.json();

if (!res.ok) {
  console.error(`Error ${body.error.code}: ${body.error.message}`);
  // Use body.meta.request_id when contacting support
} else {
  const link = body.data;
}

Request ID

Every response includes meta.request_id. Include this when reporting issues to xQR support — it helps us trace the exact request in our logs.

Detailed Error Reference

For a comprehensive guide to every error code — including common causes, fix steps, and code examples — see the Error Reference.