Error Handling

API error responses in the Scriptix API.

Error Response Format

Based on the BaseError type, API errors return this structure:

{
  "error": "Error message",
  "error_description": "Detailed error description",
  "message": "Alternative message field",
  "detail": "Additional details"
}

Fields:

• error (string) - Primary error message
• error_description (string, optional) - Detailed error description
• message (string, optional) - Alternative message field
• detail (string, optional) - Additional error details

Note: Not all fields are present in every error response.

HTTP Status Codes

The application handles these HTTP status codes:

Code	Status	User Message
400	Bad Request	"Invalid request. Please check your input."
401	Unauthorized	"Authentication required. Please log in again."
403	Forbidden	"You do not have permission to perform this action."
404	Not Found	"The requested resource was not found."
422	Unprocessable Entity	"Validation error. Please check your input."
429	Too Many Requests	"Too many requests. Please try again later."
500	Internal Server Error	"Server error. Please try again later."
503	Service Unavailable	"Service temporarily unavailable. Please try again later."

Error Message Extraction

Error responses contain a human-readable message. Read it from the error field, falling back to the message field if error is absent:

1. error
2. message
3. HTTP status code default message

Validation Errors (422)

422 errors include an error field containing the validation message.

Authentication Errors (401)

A 401 Unauthorized response means the token is missing, invalid, or expired. Re-authenticate to obtain a new token. Shared document pages use magic link authentication instead of Bearer tokens.

Support

For assistance with errors, contact: support@scriptix.io

Related Documentation

• Authentication - Authentication setup and errors
• API Overview - API introduction