Error Handling

The API uses standard HTTP status codes and returns structured JSON error responses.

HTTP status codes

Code	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Request succeeded, no body (e.g., DELETE)
`400 Bad Request`	Invalid request body or parameters
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource not found
`422 Unprocessable Entity`	Validation errors
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server-side error

Error responses include a JSON body with error details:

{
  "error": "Resource not found"
}

Validation errors include field-specific details:

{
  "errors": {
    "name": ["can't be blank"],
    "url": ["is invalid"]
  }
}

HTTP 401

{
  "error": "Authentication required"
}

Fix: Include a valid API key in the Authorization: Bearer hklst_... header.

HTTP 404

{
  "error": "Resource not found"
}

Fix: Verify the resource ID exists and belongs to your organization.

HTTP 422

{
  "errors": {
    "name": ["can't be blank"],
    "slug": ["has already been taken"]
  }
}

Fix: Check the request body for missing or invalid fields.

HTTP 400

{
  "error": "name is required"
}

Fix: Include all required parameters in the request body.