API Error Codes & Troubleshooting

The WarpLink API error response format, a reference of common error codes, and how to troubleshoot failed requests.

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 Status	Code	Description
400	`VALIDATION_ERROR`	Request body or query parameters failed validation
400	`IMMUTABLE_FIELD`	Attempted to update a field that cannot be changed
400	`INVALID_ID`	The provided ID is not a valid UUID
400	`INVALID_APP_ID`	The `app_id` does not belong to your organization
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	The key lacks the required scope. Attribution requests also return this when an API key is used instead of an SDK key
404	`NOT_FOUND`	The requested resource does not exist
409	`SLUG_TAKEN`	The custom slug is already in use
409	`DUPLICATE_APP`	An app with this bundle ID or package name exists
410	`GONE`	The link has expired
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	An unexpected server error

Troubleshooting

"UNAUTHORIZED" on every request

Verify your API key starts with wl_live_
Check the header format: Authorization: Bearer wl_live_YOUR_API_KEY
Ensure the key hasn't expired or been deleted

"FORBIDDEN" on attribution requests

Install attribution requires an SDK key. An API key cannot record installs, whatever scopes it holds
Create one at API Keys > SDK key and pass it to WarpLink.configure()
Telltale symptom: deep links resolve normally but no installs appear in your dashboard

"VALIDATION_ERROR" when creating a link

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

"SLUG_TAKEN" when creating a link

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

Errors