Errors

Status codes and the error shape.

The API uses conventional HTTP status codes: 2xx succeeded, 4xx means the request needs fixing, 5xx means something failed on our side.

Error shape

Errors return code, message and sometimes details. The code is stable and safe to branch on, like link.slug_taken or link.not_found. The message is for humans and may change.

The exception is a request whose body or query does not match the schema: it gets 422 with a detail list naming each invalid field by its location (loc).

Status codes

400	The request is malformed.
401	The API key is missing, wrong or revoked.
403	The key is valid but not allowed to do this.
404	The resource does not exist in this workspace.
409	Conflicts with existing data, e.g. a slug already in use.
422	The body or query failed validation. See below for the shape.
429	Rate limit exceeded; retry after the `Retry-After` seconds.
5xx	Something failed on our side. Safe to retry with backoff.

Error 409

{
  "code": "link.slug_taken",
  "message": "Slug 'summer-sale' is already in use"
}

Validation error 422

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "destinationUrl"
      ],
      "msg": "Field required",
      "input": {
        "name": "Summer sale"
      }
    }
  ]
}