Responses, Errors & Limits

Validation model

{
  "message": "The given data was invalid.",
  "errors": {
    "reference": ["The reference format is invalid."],
    "link": ["The link field must be a valid URL."]
  }
}

Do not parse the human message to identify a field. Use the keys of errors; display every string in the corresponding array.

Status codes

• 200: successful read or availability result
• 201: resource created
• 204: deletion on supported administrative routes
• 401: credential missing or invalid
• 403: feature or operation not permitted
• 409: hostname or reference conflict
• 410: expired or exhausted public short address
• 422: validation, quota, or domain-ownership failure
• 423: link quarantined by the destination-safety policy
• 429: rate limit
• 502/503: upstream or configured service unavailable
• 500: unexpected server error

Public short-address limits

Guest addresses use random Base62 references of at least 10 characters, remain active for 7 days, and are limited to three creations per browser session. Free uses automatic 10-character references and stops after 30 days or 30 redirects, whichever happens first. Starter uses 6-character automatic references or a custom alias; Pro uses 4-character automatic references or a custom alias. Claim preserves the exact guest reference. Served references are never reassigned.

Retry policy

• Do not retry 401, 403, 409, 410, 422, or 423 without changing the request or resolving the lifecycle or quarantine state.
• For 429, honor Retry-After when present.
• Retry 502, 503, and transient network failures with bounded exponential backoff and jitter.
• Use an idempotency strategy in the caller before retrying creation after an unknown network outcome.

Forward compatibility

Response objects may gain fields. Clients and agents should ignore unknown properties and must not rely on JSON property order.