Error management

Shlink's REST API implements the Problem Details standard for error management.

Because of this, al error response will have Content-Type: application/problem+json, and the payload will have the next properties:

  • type: A unique error code identifying the error.
  • detail: A human-friendly description of the error.
  • title: A short unique error title.
  • status: The same value returned as the responses status code.
{
  "type": "TAG_NOT_FOUND",
  "detail": "Tag with name \"foo\" could not be found",
  "title": "Tag not found",
  "status": 404
}

Some errors can have extra properties, depending on their nature.

{
  "type": "INVALID_SLUG",
  "detail": "Provided slug \"custom\" is already in use",
  "title": "Invalid custom slug",
  "status": 400,
  "customSlug": "custom"
}

Error interpretation depends on the context and the endpoint. Every endpoint includes the documentation for its specific errors.

Previous to Shlink v1.21.0, the API did not implement Problem Details. Instead, error responses used to contain only two properties, error and message.

For backwards compatibility purposes, when consuming API v1 (meaning, the path starts with /rest/v1/), both error and message will continue being returned, with the same values returned in type and detail respectively.

However, when consuming API's v2 (/rest/v2/), which has been introduced in Shlink v1.21.0, those two properties will no longer be returned.

Starting with Shlink v2.0.0, both versions of the API will behave in the same way, not returning the old error and message properties.