Errors

Most endpoints wrap successful responses in the standard envelope (data, error_code, message). Error responses instead return a flat object:

{ "code": "NOT_FOUND", "message": "Resource not found" }

details (an object) may also be present for additional context.

Confirmed codes, from GET /v1/links/{id}:

HTTP Code Meaning
400 BAD_REQUEST Invalid request format.
401 UNAUTHORIZED Missing or invalid API key.
403 FORBIDDEN Insufficient permissions for this operation.
404 NOT_FOUND The requested resource does not exist.

Other endpoints:

  • Create link, bulk-create links: 401 for missing/invalid credentials, 422 for validation failures (e.g. missing longUrl/long_url).
  • Bulk-create links additionally returns 429 Too Many Requests if you exceed your account’s rate limit — see Limits.
  • Click analytics: 401 for missing/invalid credentials, 400 for validation failures (e.g. missing group_by).
  • List domains: 401 for missing/invalid credentials.

The contract doesn’t publish a field-level error schema for the 422/400/429 responses above, so treat the body as at least { code, message } and inspect message for details.