WarpLink

Errors

Error response format, common error codes, and troubleshooting.

All API errors return a consistent JSON structure.

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Link not found",
    "details": {
      "fields": [
        { "field": "destination_url", "message": "Invalid URL format" }
      ]
    }
  }
}

The details field is optional and appears on validation errors to indicate which fields failed.

Error Codes

HTTP StatusCodeDescription
400VALIDATION_ERRORRequest body or query parameters failed validation
400IMMUTABLE_FIELDAttempted to update a field that cannot be changed
400INVALID_IDThe provided ID is not a valid UUID
400INVALID_APP_IDThe app_id does not belong to your organization
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key lacks the required scope
404NOT_FOUNDThe requested resource does not exist
409SLUG_TAKENThe custom slug is already in use
409DUPLICATE_APPAn app with this bundle ID or package name exists
410GONEThe link has expired
429RATE_LIMIT_EXCEEDEDToo many requests
500INTERNAL_ERRORAn unexpected server error

Troubleshooting

"UNAUTHORIZED" on every request

  • Verify your API key starts with wl_live_ or wl_test_
  • Check the header format: Authorization: Bearer wl_live_YOUR_KEY
  • Ensure the key hasn't expired or been deleted
  • destination_url must include the protocol (https://)
  • slug must be 2-100 characters, lowercase alphanumeric with hyphens
  • expires_at must be an ISO 8601 date in the future
  • tags is limited to 20 items, each up to 50 characters
  • Custom slugs must be unique per domain
  • Try a different slug or omit slug to auto-generate one
  • Reserved slugs (api, admin, dashboard, etc.) cannot be used

Rate Limiting

API rate limits and best practices.

API Overview

WarpLink REST API reference — authentication, rate limiting, and error handling.

On this page

Error FormatError CodesTroubleshooting"UNAUTHORIZED" on every request"VALIDATION_ERROR" when creating a link"SLUG_TAKEN" when creating a link