Errors

Every failure, whatever the status, comes back in the same envelope. You write the error handler once.

{
  "error": {
    "code": "redirect_not_found",
    "message": "Redirect not found.",
    "request_id": "req_4f3c1..."
  }
}

Just focus on `code`

code field doesn’t change within the same API version and was made for you to make sure what caused this error. While message is just a human readable string. We made it just for easier logging of possible errors in your integration. The text may be changed in the future. request_id is the same value as the X-Request-Id header. Log it on failures and quote it in support tickets — it is how we find your exact request. See Resource IDs.

Validation failures

invalid_request adds a details array with one entry per violation, so you can point a user at the field that needs fixing instead of at the request as a whole. field is a path, nested with dots, for example items.0.slug at bulk operations.

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "request_id": "req_4f3c1e8ab29d4d7fa1c6e05b7d9a2f31",
    "details": [
      { "field": "name", "code": "max_length", "message": "name must be shorter than 100 characters" },
      { "field": "target_url", "code": "invalid_url", "message": "target_url must be a valid http(s) URL" }
    ]
  }
}

Codes inside details are their own set and never overlap with the catalogue below.

`code`	When
`required`	A required field is missing or empty
`invalid_type`	Wrong type
`min_length` / `max_length`	String length out of range
`min_value` / `max_value`	Number out of range
`min_items` / `max_items`	Array size out of range
`duplicate_items`	Repeated values in an array
`invalid_url`	Not an http(s) address
`invalid_format`	Did not match a mask: slug, hostname
`invalid_date`	Not ISO 8601
`invalid_value`	Value outside the allowed set
`unknown_field`	Field is not part of the contract

Fields with unknown/incorrect names also count as a validation error.

Catalogue

HTTP	`code`	When
400	`invalid_request`	Invalid body, parameters or public id
400	`domain_not_found`	`domain` is not one of yours or the system domain
400	`domain_not_active`	Domain exists but verification is not complete
400	`slug_required_for_system_domain`	A slug is required on the system domain
401	`invalid_api_key`	Key missing, unknown or revoked
403	`account_suspended`	The account owning the key is suspended
403	`api_access_not_available_on_current_plan`	Your plan does not include the API
403	`feature_not_available_on_current_plan`	Your plan does not include this feature
403	`plan_limit_reached`	Entity limit of your plan reached
403	`analytics_range_exceeds_plan_limit`	Requested period is deeper than your plan allows
404	`redirect_not_found`	Redirect not found, or not yours
404	`landing_not_found`	Landing page not found, or not yours
404	`group_not_found`	Group not found, or not yours
404	`domain_not_found`	Domain from the path not found, or not yours
409	`slug_already_taken`	The address is taken
409	`hostname_already_taken`	The hostname is connected to another account
409	`hostname_is_system_domain`	The hostname belongs to the platform
409	`analytics_not_configured`	This link has no analytics attached, and never will
413	`payload_too_large`	Request body exceeds 100 KB
415	`unsupported_media_type`	`Content-Type` must be `application/json`
429	`rate_limit_exceeded`	Per-minute limit, or too many rejected requests from your address
429	`daily_quota_exceeded`	Daily quota exhausted
500	`internal_error`	Everything else
503	`domain_provider_unavailable`	The domain provider did not respond
503	`analytics_temporarily_unavailable`	The analytics store did not respond

Two more codes appear only inside bulk responses: duplicate_id_in_batch and duplicate_slug_in_batch. See Bulk operations.

New codes can appear for new scenarios without a new major version, so give your handler a fallback branch that keys off the HTTP status class. See Forward compatibility.

Getting Started

Core Concepts

Working with the API

Just focus on `code`

Validation failures

Catalogue

​Just focus on code

​Validation failures

​Catalogue

Just focus on `code`

Validation failures

Catalogue