guidewire-common-errors

Guidewire Common Errors

Overview

Diagnose and resolve the most common errors encountered in Guidewire InsuranceSuite Cloud API, Gosu development, and integrations.

Prerequisites

• Access to Guidewire Cloud Console logs
• Understanding of HTTP status codes
• Familiarity with Gosu exception handling

HTTP Status Code Reference

Code	Meaning	Common Cause	Resolution
400	Bad Request	Malformed JSON, invalid field	Check request body structure
401	Unauthorized	Invalid/expired token	Refresh OAuth token
403	Forbidden	Missing API role	Check role assignments in GCC
404	Not Found	Invalid endpoint or ID	Verify URL and resource ID
409	Conflict	Concurrent modification	Retry with updated checksum
422	Unprocessable	Business rule violation	Fix validation errors
429	Too Many Requests	Rate limit exceeded	Implement backoff
500	Server Error	Internal error	Check server logs
503	Service Unavailable	Maintenance/overload	Retry with backoff

Common Validation Error Codes

Code	Description	Example
required	Missing required field	accountHolder is required
invalid_format	Wrong data format	dateOfBirth must be ISO date
invalid_value	Value not in allowed set	state.code 'XX' not valid
range_exceeded	Value outside range	premium exceeds policy limit
duplicate	Duplicate entity	Account number already exists
reference_not_found	Invalid foreign key	producerCode.id not found

Instructions

Step 1: Identify the Error Category

Check HTTP status code and error response body to determine if the issue is authentication (401/403), validation (422), concurrency (409), or rate limiting (429).

Step 2: Apply the Correct Fix Pattern

• 401: Implement automatic token refresh with 60-second pre-expiry buffer
• 403: Add required API role in GCC Identity & Access, wait 5 minutes for propagation
• 409: Implement retry with GET-then-PATCH loop using checksums
• 422: Parse validation details by field and code, fix each violation

Step 3: Handle Gosu-Specific Exceptions

Key patterns: use null-safe operators (?., ?:), add entities to bundles before modifying, handle AtMostOneRow for multi-result queries, and catch ValidationException during commits.

Step 4: Handle Integration Errors

Use circuit breakers for external services, retry message queue deliveries with exponential backoff (max 3 retries), and implement deadlock detection for database operations.

For detailed code implementations (TypeScript, Gosu, error wrappers), load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Output

• Error identified and categorized
• Appropriate fix pattern applied
• Error handling code implemented

Error Handling

Error	Cause	Solution
Token refresh loop	Invalid credentials	Verify client ID/secret in GCC
Checksum mismatch	Stale data	Re-fetch before update
Validation cascade	Dependent fields	Fix root field first
Deadlock timeout	Lock contention	Add retry with backoff

Resources

• Cloud API Error Reference
• Gosu Exception Handling
• Integration Troubleshooting

Next Steps

For debugging techniques, see guidewire-debug-bundle.

Examples

Basic usage: Apply guidewire common errors to a standard project setup with default configuration options.

Advanced scenario: Customize guidewire common errors for production environments with multiple constraints and team-specific requirements.