> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dashlink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> One error shape, a stable set of codes, and what to do about each.

Every failure returns the same shape, whatever went wrong and whichever endpoint it happened on.

```json theme={null}
{
  "error": {
    "message": "Shortlink not found.",
    "status_code": 404,
    "code": "NOT_FOUND",
    "details": {}
  }
}
```

| Field | Always present | Use it for |
| - | - | - |
| `message` | Yes | Showing a human what happened |
| `status_code` | Yes | Matches the HTTP status |
| `code` | Usually | Branching in code |
| `details` | Sometimes | Identifying the offending parameter |

> [!WARNING]
>
> Branch on `code`, never on `message`. Messages are written for people and are translated and reworded; codes are a contract and will not change under you.

## Detecting a failure

`data` and `error` are mutually exclusive, so one check covers everything:

```bash cURL theme={null}
curl -s "https://api.dashlink.ai/api/v1/shortlinks/get_shortlinks?per_page=1" \
  -H "X-API-Key: $DASHLINK_API_KEY" \
  | jq 'if .error then error(.error.message) else .data end'
```

```javascript Node.js theme={null}
const payload = await response.json();

if (payload.error) {
  throw new DashlinkError(payload.error.message, payload.error.code);
}

const result = payload.data;
```

```python Python theme={null}
payload = response.json()

if "error" in payload:
    error = payload["error"]
    raise DashlinkError(error["message"], code=error.get("code"))

result = payload["data"]
```

```go Go theme={null}
var payload struct {
	Data  json.RawMessage `json:"data"`
	Error *struct {
		Message string `json:"message"`
		Code    string `json:"code"`
	} `json:"error"`
}

if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
	return nil, err
}

if payload.Error != nil {
	return nil, &DashlinkError{Message: payload.Error.Message, Code: payload.Error.Code}
}

return payload.Data, nil
```

```ruby Ruby theme={null}
payload = JSON.parse(response.body)

if payload.key?("error")
  raise DashlinkError.new(payload["error"]["message"], payload["error"]["code"])
end

result = payload["data"]
```

```php PHP theme={null}
<?php
$payload = json_decode($response, true);

if (isset($payload['error'])) {
    throw new DashlinkError(
        $payload['error']['message'],
        $payload['error']['code'] ?? null
    );
}

$result = $payload['data'];
```

## Status codes

| Status | Meaning | Retry? |
| - | - | - |
| `400` | The request is wrong | No — fix the request |
| `401` | Not authenticated | No — fix the key |
| `403` | Authenticated, not allowed | No — fix the permissions |
| `404` | No such resource, or not yours | No |
| `409` | Conflicts with something that exists | No — choose different values |
| `429` | Rate limited | Yes, after `Retry-After` |
| `500` | Our fault | Yes, with backoff |

## Error codes

### Authentication and permissions

| Code | Status | What it means |
| - | - | - |
| `AUTHENTICATION_REQUIRED` | 401 | No key sent, or it is malformed |
| `AUTHENTICATION_FAILED` | 401 | Key not recognised, expired, or revoked |
| `PERMISSION_DENIED` | 403 | Key lacks the module grant, or holds `read` where `write` is needed |
| `ORGANIZATION_REQUIRED` | 403 | The key is not attached to an organization |
| `NO_ORGANIZATION` | 400 | No organization context could be resolved |

### Request problems

| Code | Status | What it means |
| - | - | - |
| `MISSING_PARAMETER` | 400 | A required parameter was absent |
| `INVALID_PARAMETER` | 400 | A parameter was present but not acceptable |
| `VALIDATION_ERROR` | 400 | Failed a business rule rather than a type check |

`INVALID_PARAMETER` usually carries `details` naming the parameter and listing what is accepted:

```json theme={null}
{
  "error": {
    "message": "Invalid sort_by option. Choose from name, most_recent, last_modified",
    "status_code": 400,
    "code": "INVALID_PARAMETER",
    "details": {
      "parameter": "sort_by",
      "value": "most_clicked",
      "valid_options": ["name", "most_recent", "last_modified"]
    }
  }
}
```

### Resources

| Code | Status | What it means |
| - | - | - |
| `NOT_FOUND` | 404 | No such resource — or it belongs to another organization |
| `DUPLICATE_ENTRY` | 409 | Already exists. Usually a back-half taken on that domain |
| `LINK_EXISTS` | 409 | Something still references what you are deleting |

> [!NOTE]
>
> `NOT_FOUND` covers both "does not exist" and "not yours", deliberately. Distinguishing them would confirm that an id is real, which is enough to map another customer's resources by trying ids until the status changes.

### Limits

| Code | Status | What it means |
| - | - | - |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests this minute |
| `INTERNAL_SERVER_ERROR` | 500 | Our fault |

### Plan and subscription

These are all about what your plan permits, not what your request said. Retrying does not help; the account has to change.

| Code | Status | What it means |
| - | - | - |
| `FEATURE_LIMIT_EXCEEDED` | 403 | Your plan includes this, but the allowance is used up |
| `FEATURE_ACCESS_DENIED` | 403 | A paid-only capability — Dynamic Traffic Routing, Link Expiration — on a plan without it |
| `FEATURE_NOT_AVAILABLE_IN_PLAN` | 403 | The feature is absent from the plan entirely, rather than exhausted |
| `SUBSCRIPTION_REQUIRED` | 403 | The allowance could not be evaluated because there is no active subscription |
| `NO_SUBSCRIPTION` | 403 | No subscription at all |
| `PLAN_NOT_FOUND` | 404 | The organization has no resolvable plan |

> [!NOTE]
>
> The distinction that matters when handling these: `FEATURE_LIMIT_EXCEEDED` means you have the feature and ran out of it, so deleting resources or waiting for a billing period can clear it. The rest mean the plan does not include the feature at all, and only an upgrade changes the answer.

Call [`get_feature_limits`](https://docs.dashlink.ai/api-reference/account/overview) before a large bulk create to fail early instead of halfway through.

## Errors inside bulk operations

A bulk call does **not** return an error envelope when individual items fail. The request succeeded; some items did not. The outcome is inside `data`:

```json theme={null}
{
  "data": {
    "status": "partial_success",
    "summary": { "total": 3, "succeeded": 1, "failed": 1, "skipped": 1 },
    "results": [
      { "index": 0, "outcome": "success", "name": "SHORT-0001", "error": null },
      { "index": 1, "outcome": "skipped", "name": "SHORT-0002",
        "error": { "message": "Not found.", "code": "NOT_FOUND" } },
      { "index": 2, "outcome": "error", "name": "SHORT-0003",
        "error": { "message": "Permission denied.", "code": "PERMISSION_DENIED" } }
    ]
  }
}
```

Check `status` first: `success`, `partial_success`, or `error`. Then walk `results` for the items that need attention.

> [!WARNING]
>
> A `200` on a bulk call does not mean every item worked. Always read `summary.failed`.

Set `stop_on_error=true` if you would rather the whole batch roll back at the first failure than land partially applied.

## A retry policy that works

```python theme={null}
RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retry(request_fn, max_attempts=4):
    for attempt in range(max_attempts):
        response = request_fn()

        if response.status_code not in RETRYABLE:
            return response

        # 4xx other than 429 will fail identically however many times
        # we send it, so only these are worth repeating.
        wait = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait)

    return response
```

Retrying a `400` or a `403` wastes your rate limit on a request that cannot succeed until you change it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.