Diagnose and resolve the most common errors encountered in Guidewire InsuranceSuite Cloud API, Gosu development, and integrations.
| 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 |
| 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 |
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).
Key patterns: use null-safe operators (?., ?:), add entities to bundles before modifying, handle AtMostOneRow for multi-result queries, and catch ValidationException during commits.
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)
| 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 |
For debugging techniques, see guidewire-debug-bundle.
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.
