Error Handling

Overview

The STACKIT Domain Services API uses standardized HTTP status codes to indicate the success or failure of an API request. In the event of an error, the API returns a structured JSON object of type application/problem+json to help you identify the cause of the problem.

The Error Object (Problem Details)

Every error response contains a machine-readable and human-readable body to simplify debugging.

Field	Description
type	A machine-readable error code (slug) identifying the error type.
title	A short, human-readable summary of the error.
status	The HTTP status code (e.g., 403).
detail	A specific explanation of what went wrong in this particular case.
instance	The URI path of the endpoint where the error occurred.

Error Code Reference

The following table lists the most common status codes you might encounter:

Status	Error Type (Slug)	Description
400	bad-request	Invalid Request: A required field is missing (e.g., name) or the format is invalid (e.g., incorrect email format).
401	unauthorized	Not Authenticated: The Bearer token is missing, expired, or invalid.
403	forbidden	Permission Denied: Your token is valid, but you do not have rights for the requested organizationId.
404	not-found	Not Found: The requested resource (e.g., domainId or dnsZoneId) does not exist.
409	conflict	Conflict: The resource already exists (e.g., duplicate domain) or is currently in use and cannot be deleted.
429	too-many-requests	Rate Limit: You have exceeded the limit for API requests. Please wait before retrying.
500	internal-server-error	Server Error: An unexpected error occurred on our side. Please try again later.
503	service-unavailable	Service Unavailable: A subsystem (e.g., an external registry) is temporarily unreachable.

Example Error Response

If you attempt to create a DNS record in a zone that does not belong to your organization, the API will respond as follows:

{
  "type": "forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to access this resource.",
  "instance": "/api/v1/organizations/85ba9ac6.../dns-zones/primary"
}