Ulinkly REST API typed errors

REST failures use RFC 9457 Problem Details with the application/problem+json media type. Every problem includes a stable machine-readable code and the standard type, title, status, detail, and instance members.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Project not found",
  "instance": "/v1/projects/missing",
  "code": "NOT_FOUND",
  "statusCode": 404,
  "message": "Project not found",
  "error": "Not Found"
}

For status-based problems, type is RFC 9457's about:blank; the stable code extension provides the machine-readable Ulinkly reason. The statusCode, message, and error extension members preserve compatibility with existing Ulinkly SDKs. New integrations should branch on status and code, not parse detail or message text. Clients must ignore extension members they do not recognize.

Validation errors

Validation failures use VALIDATION_ERROR. The errors extension contains one object per validation issue:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "name must be a string; fallbackUrl must be a URL",
  "instance": "/v1/sdk/links",
  "code": "VALIDATION_ERROR",
  "statusCode": 400,
  "message": [
    "name must be a string",
    "fallbackUrl must be a URL"
  ],
  "error": "Bad Request",
  "errors": [
    { "detail": "name must be a string" },
    { "detail": "fallbackUrl must be a URL" }
  ]
}

Stable codes

Code	Typical status	Meaning
BAD_REQUEST	400	The request cannot be processed as sent.
VALIDATION_ERROR	400	One or more request fields failed validation.
UNAUTHORIZED	401	The API credential is missing, invalid, or expired.
FORBIDDEN	403	The credential is valid but cannot perform the operation.
NOT_FOUND	404	The requested resource does not exist in the credential's scope.
CONFLICT	409	The request conflicts with current resource state.
RATE_LIMIT_EXCEEDED	429	Pause until the Retry-After delay expires.
INTERNAL_SERVER_ERROR	500	Retry only idempotent requests with backoff.
SERVICE_UNAVAILABLE	503	The service is temporarily unavailable; retry with backoff.

Unknown 5xx failures deliberately omit internal exception details.