Skip to main content

​
What are Problem Types?

The Guile API uses RFC 9457 Problem Details for HTTP APIs to provide structured error responses. When an API operation fails, you’ll receive a response with the content type application/problem+json that includes detailed information about what went wrong. Each problem response includes:
  • id: A unique identifier for this problem occurrence
  • type: A URI that identifies the specific problem type
  • title: A short, human-readable summary of the problem
  • status: The HTTP status code
  • detail: A human-readable explanation specific to this occurrence
  • instance: A URI reference that identifies the specific occurrence
  • attributes: Additional data specific to the problem type (optional)

​
General HTTP Errors

Standard HTTP error responses formatted as problem types.

​
Service-Specific Errors

Error types specific to service operations. Operations may return additional problem types specific to their functionality.

​
Using Problem Types

When you encounter an error response, check the type field to understand the specific problem. Each problem type has its own documentation page with:
  • Detailed description of when this problem occurs
  • Specific remediation steps
  • Additional attributes that may be included
The problem type URI serves as both an identifier and a link to the documentation, making it easy to understand and resolve issues programmatically or manually. Problems are listed per operation per response in the API Reference.

​
Error Handling Best Practices

  1. Always check the problem type - Don’t rely solely on HTTP status codes
  2. Read the detail field - It provides context specific to your request
  3. Handle known problem types - Implement specific logic for common problems
  4. Log the instance URI - It helps with debugging and support requests
  5. Follow remediation guidance - Each problem type includes specific steps to resolve the issue