Skip to main content

​
Error Response Format

All API errors follow a consistent JSON structure that includes an error code, human-readable message, and request ID for troubleshooting.

​
Error Response Structure

When an error occurs, the API returns a JSON response with the following structure: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "request_id": "unique-request-identifier",
    "details": {
      "field_name": "validation error message"
    }
  }
}
​
error
object
required
The error object containing all error information
​
code
string
required
Machine-readable error code identifying the type of error
​
message
string
required
Human-readable description of the error
​
request_id
string
required
Unique identifier for the request, useful for troubleshooting and support
​
details
object
Additional error details, typically used for validation errors to specify which fields failed validation

​
Error Codes

The API uses standard HTTP status codes along with specific error codes to indicate the type of error.

​
UNAUTHORIZED

HTTP Status: 401 Unauthorized Returned when authentication is missing or invalid. 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "missing bearer token",
    "request_id": "req_abc123"
  }
}
Common Causes:
  • Missing Authorization header
  • Invalid or expired access token
  • Attempting to access a resource you don’t own
Reference: See internal/auth/middleware.go:27 and internal/versions/handler.go:35

​
NOT_FOUND

HTTP Status: 404 Not Found Returned when the requested resource does not exist. 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "prompt not found",
    "request_id": "req_def456"
  }
}
Common Causes:
  • Requesting a prompt that doesn’t exist
  • Requesting a version that doesn’t exist
  • Using an invalid prompt or version ID
Reference: See internal/versions/handler.go:50

​
CONFLICT

HTTP Status: 409 Conflict Returned when the request conflicts with existing data. 
{
  "error": {
    "code": "CONFLICT",
    "message": "version already exists",
    "request_id": "req_ghi789"
  }
}
Common Causes:
  • Attempting to create a prompt that already exists
  • Attempting to create a version that already exists
  • Duplicate resource creation
Reference: See internal/versions/handler.go:68 and internal/prompts/handler.go:64

​
VALIDATION_FAILED

HTTP Status: 400 Bad Request Returned when request validation fails. This error includes a details object with field-specific error messages. 
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "validation failed",
    "request_id": "req_jkl012",
    "details": {
      "name": "name is required",
      "version": "version must be semver format"
    }
  }
}
Common Causes:
  • Missing required fields
  • Invalid field formats
  • Field values outside allowed ranges
  • Missing OAuth parameters
The details field provides specific information about which fields failed validation and why.
Reference: See internal/server/respond.go:33 (RespondValidationError function)

​
INTERNAL_ERROR

HTTP Status: 500 Internal Server Error Returned when an unexpected server error occurs. 
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "failed to upload tarball",
    "request_id": "req_mno345"
  }
}
Common Causes:
  • Database connection failures
  • Storage service failures
  • Unexpected server-side errors
If you encounter internal errors repeatedly, please contact support with the request_id for investigation.
Reference: See internal/versions/handler.go:83 and internal/server/server.go:56

​
Best Practices

​
Always Check the Error Code

Use the code field to programmatically handle different error types: 
try {
  const response = await fetch('https://api.prompts.dev/v1/prompts', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.error.code) {
      case 'UNAUTHORIZED':
        // Refresh token or redirect to login
        break;
      case 'NOT_FOUND':
        // Show 404 page
        break;
      case 'VALIDATION_FAILED':
        // Display field-specific errors
        console.log(error.error.details);
        break;
      default:
        // Handle unexpected errors
        break;
    }
  }
} catch (err) {
  console.error('Network error:', err);
}

​
Log Request IDs

Always log the request_id when errors occur. This helps with debugging and support inquiries: 
if (error.error.request_id) {
  console.error(`Error [${error.error.request_id}]: ${error.error.message}`);
}

​
Handle Validation Errors Gracefully

For VALIDATION_FAILED errors, iterate through the details object to display field-specific errors: 
if (error.error.code === 'VALIDATION_FAILED' && error.error.details) {
  Object.entries(error.error.details).forEach(([field, message]) => {
    showFieldError(field, message);
  });
}

Build docs developers (and LLMs) love

Get started for freeTalk to us