<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

<a id="component-eol-banner"></a>

You are viewing **Develocity Provenance Governor 1.6**. To view the latest available version of the docs, see [1.7](https://docs.gradle.com/develocity/provenance-governor/1.7/api-errors/).

# Error Handling

<a id="preamble"></a>

This reference documents all error responses returned by the Develocity Provenance Governor REST API. All errors follow the [RFC 7807 Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807) standard.

<a id="overview"></a>

## Overview

The Develocity Provenance Governor REST API uses RFC 7807 Problem Details to provide consistent, machine-readable error responses. Each error response includes structured information about what went wrong and how to resolve it.

<a id="problem-detail-format"></a>

### Problem Detail Format

All error responses return a JSON object with the following structure:

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid package coordinates provided: namespace is required for maven packages",
  "instance": "/packages/maven/acme-app/1.0.0/attestations"
}
```

<a id="standard-fields"></a>

#### Standard Fields

 
| Field | Description |
| --- | --- |
| type | A URI reference that identifies the problem type. For Develocity Provenance Governor, these follow the pattern urn:gradle:develocity:provenance-governor:problems:. |
| title | A short, human-readable summary of the problem type. |
| status | The HTTP status code for this occurrence of the problem. |
| detail | A human-readable explanation specific to this occurrence of the problem. |
| instance | A URI reference that identifies the specific occurrence of the problem (typically the request path). |

<a id="optional-fields"></a>

#### Optional Fields

Some error responses include additional properties in a `properties` object or as top-level fields:

 
| Field | Description |
| --- | --- |
| request | Details about the request that caused the error (included in some 500-level errors). |
| successes | For partial failures, lists successful operations that completed before the error (attestation publishing). |
| errors | For partial failures, lists operations that failed with detailed error information. |
| buildEventRequest | Details about the build event request that failed (Develocity retrieval errors). |
| responseBody | The response body from a failed external service call. |
| responseHeaders | The response headers from a failed external service call. |

<a id="problem-types"></a>

## Problem Types

The following problem types are defined for the Develocity Provenance Governor REST API:

  
| Problem Type | Status | Description |
| --- | --- | --- |
| Bad Request | 400 | Invalid request input, malformed data, or validation failures |
| Not Found | 404 | Requested resource does not exist |
| Rate Limit Exceeded | 429 | Too many concurrent requests, service under high load |
| External Service Failure | 500 | External service communication failure |
| Internal Server Error | 500 | Unexpected server error |

<a id="bad-request"></a>

## Bad Request (400)

**Problem Type URN:** `urn:gradle:develocity:provenance-governor:problems:bad-request`

**HTTP Status:** 400 Bad Request

<a id="bad-request-description"></a>

### Description

This error occurs when the request contains invalid input data, malformed parameters, or fails validation constraints. The client should modify the request before retrying.

<a id="bad-request-common-causes"></a>

### Common Causes

*   Invalid package coordinates (missing namespace for Maven packages)
    
*   Malformed repository URL (incorrect format)
    
*   Missing required fields (`sha256`, `repositoryUrl`)
    
*   Invalid SHA-256 hash format (not 64 hexadecimal characters)
    
*   Unsupported package type
    
*   Invalid package version format
    

<a id="bad-request-example-invalid-repo"></a>

### Example: Invalid Repository URL

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/attestations \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "https://repo.example.com/maven-repo",
  "buildScan": {
    "ids": ["abc123xyz"]
  }
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid repositoryUrl provided [https://repo.example.com/maven-repo] must be formatted as pass:[${repositoryHost}]/pass:[${repositoryName}]",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/attestations"
}
```

<a id="bad-request-example-unsupported-type"></a>

### Example: Unsupported Package Type

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/npm/@scope/acme-package/1.0.0/attestations \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "registry.npmjs.org/npm-repo"
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Package type [npm] is currently not supported.",
  "instance": "/packages/npm/@scope/acme-package/1.0.0/attestations"
}
```

<a id="bad-request-example-missing-fields"></a>

### Example: Missing Required Fields

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/policy-scans/build \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497"
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request content. Bad criteria (sha256 or repositoryUrl).",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/policy-scans/build"
}
```

<a id="bad-request-troubleshooting"></a>

### Troubleshooting

 
| Error Message Pattern | Solution |
| --- | --- |
| "Invalid repositoryUrl" | Ensure the repository URL follows the format ${repositoryHost}/${repositoryName} without protocol (e.g., repo.example.com/maven2) |
| "Package type \[…​\] is currently not supported" | Use a supported package type: maven or oci |
| "Bad criteria (sha256 or repositoryUrl)" | Verify both sha256 and repositoryUrl are present and non-empty in the request body |
| "Invalid package coordinates" | Check that package coordinates match the expected format for the package type (Maven requires namespace) |

> [!TIP]
> Repository URL Format: The repository URL should not include the protocol (https://) and should use the format hostname/repository-name. For example: Correct: artifactory.example.com/maven-releases Incorrect: https://artifactory.example.com/maven-releases

<a id="not-found"></a>

## Not Found (404)

**Problem Type URN:** `urn:gradle:develocity:provenance-governor:problems:not-found`

**HTTP Status:** 404 Not Found

<a id="not-found-description"></a>

### Description

This error occurs when the requested resource does not exist. This could be a Policy Scan™ definition, attestation, or package that cannot be found.

<a id="not-found-common-causes"></a>

### Common Causes

*   Policy Scan definition does not exist
    
*   Attestation not found at specified storage location
    
*   Package coordinates do not match any published attestations
    
*   Storage instance not configured
    
*   Incorrect attestation ID or storage instance identifier
    

<a id="not-found-example-scan-not-found"></a>

### Example: Policy Scan™ Not Found

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/policy-scans/production-gate \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "repo.example.com/maven2"
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Policy scan 'production-gate' not found",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/policy-scans/production-gate"
}
```

<a id="not-found-example-attestation-not-found"></a>

### Example: Attestation Not Found

```bash
curl --request GET \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/sha256:73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497/attestations/s3:prod/nonexistent-uuid \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'accept: application/json'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "No attestation found matching request.",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/sha256:73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497/attestations/s3:prod/nonexistent-uuid"
}
```

<a id="not-found-troubleshooting"></a>

### Troubleshooting

 
| Error Message Pattern | Solution |
| --- | --- |
| "Policy scan '…​' not found" | Verify the Policy Scan definition exists in your policies configuration. Check kubectl get configmap policies -n develocity-provenance-governor for defined PolicyScanDefinitions. |
| "No attestation found matching request" | Confirm attestations were published for this package before attempting retrieval. Check the storage instance name matches your configuration. |
| Storage instance errors | Verify the storage instance (e.g., s3:prod, af:main) is configured in your application properties and the instance name is correct. |

> [!TIP]
> Checking Available Policy Scan Definitions: To list all configured Policy Scan definitions: Look for resources with kind: PolicyScanDefinition in the ConfigMap data.

<a id="rate-limit-exceeded"></a>

## Rate Limit Exceeded (429)

**Problem Type URN:** `urn:gradle:develocity:provenance-governor:problems:rate-limit-exceeded`

**HTTP Status:** 429 Too Many Requests

<a id="rate-limit-exceeded-description"></a>

### Description

This error occurs when the service is experiencing too many concurrent requests, causing connection pool exhaustion or reactive backpressure. This is a temporary condition that typically resolves within seconds.

<a id="rate-limit-exceeded-common-causes"></a>

### Common Causes

*   Too many concurrent API requests
    
*   Connection pool exhausted (all connections in use)
    
*   Reactive streams backpressure from downstream services
    
*   High load on the Develocity Provenance Governor instance
    

<a id="rate-limit-exceeded-example"></a>

### Example

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/policy-scans/build \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "repo.example.com/maven2"
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "The service is experiencing too many requests. Please try again later.",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/policy-scans/build"
}
```

<a id="rate-limit-exceeded-troubleshooting"></a>

### Troubleshooting

> [!TIP]
> Retry Strategy: When receiving a 429 response, implement exponential backoff retry logic: Wait 1 second, then retry If still failing, wait 2 seconds, then retry If still failing, wait 4 seconds, then retry Continue doubling the wait time up to a maximum (e.g., 30 seconds) The connection pool exhaustion typically resolves within seconds as in-flight requests complete.

**Mitigation Strategies:**

*   Reduce the number of concurrent requests to the API
    
*   Implement request queuing with controlled concurrency on the client side
    
*   Scale the Develocity Provenance Governor deployment (increase replicas)
    
*   Increase the connection pool size in the application configuration
    
*   Review and optimize slow policy evaluations that may hold connections longer
    

**Scaling the Deployment:**

```bash
kubectl scale deployment/api --replicas=3 -n develocity-provenance-governor
```

<a id="external-service-failure"></a>

## External Service Failure (500)

**Problem Type URN:** `urn:gradle:develocity:provenance-governor:problems:external-service-failure`

**HTTP Status:** 500 Internal Server Error

<a id="external-service-failure-description"></a>

### Description

This error occurs when the Develocity Provenance Governor cannot communicate with an external service such as Develocity, S3 storage, or Artifactory. This indicates a network or configuration issue with external dependencies.

<a id="external-service-failure-common-causes"></a>

### Common Causes

*   Develocity server unreachable or returning errors
    
*   S3 bucket unavailable or incorrect credentials
    
*   Artifactory repository unreachable
    
*   Network connectivity issues
    
*   Incorrect external service URLs in configuration
    
*   Authentication failures with external services
    
*   External service timeouts
    

<a id="external-service-failure-example-refused"></a>

### Example: Develocity Unreachable

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/attestations \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "repo.example.com/maven2",
  "buildScan": {
    "ids": ["abc123xyz"]
  }
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:external-service-failure",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An error occurred while trying to communicate with an external service: Connection refused",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/attestations"
}
```

<a id="external-service-failure-example-retrieval-error"></a>

### Example: Build Event Retrieval Error

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/attestations \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "repo.example.com/maven2",
  "buildScan": {
    "ids": ["invalid-build-scan-id"]
  }
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:external-service-failure",
  "title": "Build Event Retrieval Error",
  "status": 500,
  "detail": "Failed to retrieve build events from Develocity: Build scan not found",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/attestations",
  "buildEventRequest": {
    "buildScanId": "invalid-build-scan-id",
    "develocityInstance": "https://develocity.example.com"
  },
  "responseBody": "{\"error\":\"Build scan not found\"}",
  "responseHeaders": {
    "content-type": "application/json",
    "date": "Mon, 27 Jan 2026 10:15:30 GMT"
  }
}
```

<a id="external-service-failure-example-partial-failure"></a>

### Example: Partial Storage Failure

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/attestations \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "repo.example.com/maven2",
  "buildScan": {
    "ids": ["abc123xyz"]
  }
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:external-service-failure",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Failed to publish attestations to all storage targets. 1 succeeded, 1 failed.",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/attestations",
  "request": {
    "packageCoordinates": "pkg:maven/com.example/acme-app@1.0.0",
    "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
    "repositoryUrl": "repo.example.com/maven2"
  },
  "successes": [
    {
      "status": "SUCCESS",
      "store": "s3:primary"
    }
  ],
  "errors": [
    {
      "status": "FAILED",
      "store": "s3:backup",
      "message": "Request timed out: Connection timeout after 30000ms",
      "uri": "https://backup-bucket.s3.us-west-2.amazonaws.com"
    }
  ]
}
```

<a id="external-service-failure-troubleshooting"></a>

### Troubleshooting

 
| Error Pattern | Solution |
| --- | --- |
| "Connection refused" | Verify the external service URL is correct and the service is running. Check network connectivity from the Develocity Provenance Governor pod. |
| "Connection timeout" | The external service is slow to respond or unreachable. Check network routes, firewall rules, and service health. |
| "Build scan not found" | Verify the build scan ID exists in Develocity and the access key has permission to read it. |
| "Unauthorized" or "Forbidden" | Check that credentials for the external service (Develocity access key, S3 credentials, Artifactory token) are correct and have appropriate permissions. |
| S3 bucket errors | Verify the S3 bucket exists, credentials are valid, and the bucket region is correctly configured. |
| Artifactory errors | Verify the Artifactory repository exists, URL is correct, and authentication token has read/write permissions. |

**Diagnostic Commands:**

Check Develocity connectivity from the pod:

```bash
kubectl exec -it deployment/api -n develocity-provenance-governor -- curl -v https://develocity.example.com
```

Check S3 connectivity:

```bash
kubectl exec -it deployment/api -n develocity-provenance-governor -- curl -v https://acme-attestations-bucket.s3.amazonaws.com
```

Review application logs for detailed error messages:

```bash
kubectl logs deployment/api -n develocity-provenance-governor --tail=100
```

<a id="internal-server-error"></a>

## Internal Server Error (500)

**Problem Type URN:** `urn:gradle:develocity:provenance-governor:problems:internal-server-error`

**HTTP Status:** 500 Internal Server Error

<a id="internal-server-error-description"></a>

### Description

This error occurs when an unexpected error happens within the Develocity Provenance Governor application. This typically indicates a programming error, configuration issue, or unexpected state that was not properly handled.

<a id="internal-server-error-common-causes"></a>

### Common Causes

*   Unhandled exceptions in the application code
    
*   Configuration errors (malformed policy definitions)
    
*   Resource exhaustion (memory, file descriptors)
    
*   Database or persistent storage issues
    
*   Programming errors or edge cases not properly handled
    

<a id="internal-server-error-example"></a>

### Example

```bash
curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/policy-scans/build \
  --header 'authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
  --header 'content-type: application/json' \
  --data '{
  "sha256": "73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497",
  "repositoryUrl": "repo.example.com/maven2"
}'
```

**Response:**

```json
{
  "type": "urn:gradle:develocity:provenance-governor:problems:internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing the request",
  "instance": "/packages/maven/com.example/acme-app/1.0.0/policy-scans/build"
}
```

<a id="internal-server-error-troubleshooting"></a>

### Troubleshooting

**When you receive this error:**

1.  **Check Application Logs:** Review the logs for stack traces and error details:
    
    ```bash
    kubectl logs deployment/api -n develocity-provenance-governor --tail=200
    ```
    
2.  **Verify Configuration:** Check that all ConfigMaps and Secrets are properly formatted:
    
    ```bash
    kubectl get configmap policies -n develocity-provenance-governor -o yaml
    kubectl get configmap properties -n develocity-provenance-governor -o yaml
    kubectl get secret secrets -n develocity-provenance-governor -o yaml
    ```
    
3.  **Check Resource Usage:** Verify the pod has sufficient memory and CPU:
    
    ```bash
    kubectl top pod -n develocity-provenance-governor
    kubectl describe pod -n develocity-provenance-governor -l app=api
    ```
    
4.  **Review Recent Changes:** If the error started occurring recently, review any configuration or policy changes.
    
5.  **Contact Support:** If the issue persists, gather the following information and contact support:
    
    *   Full error response from the API
        
    *   Application logs (`kubectl logs deployment/api -n develocity-provenance-governor`)
        
    *   Pod description (`kubectl describe pod -n develocity-provenance-governor -l app=api`)
        
    *   Recent configuration changes
        
    

> [!WARNING]
> Internal server errors should be rare. If you encounter these errors frequently, it may indicate a bug in the application or a configuration issue that needs attention.

<a id="error-response-examples-by-endpoint"></a>

## Error Response Examples by Endpoint

<a id="error-response-publish-attestations"></a>

### Publish Attestations

Common errors when publishing attestations to `/packages/{type}/{namespace}/{name}/{version}/attestations`:

  
| Status | Problem Type | Scenario |
| --- | --- | --- |
| 400 | bad-request | Invalid package coordinates, malformed repository URL, missing required fields |
| 401 | N/A (handled by Spring Security) | Missing or invalid authentication credentials |
| 403 | N/A (handled by Spring Security) | User lacks publish-attestations permission for this package/repository |
| 500 | external-service-failure | Cannot retrieve build scans from Develocity, S3 storage unavailable |
| 500 | internal-server-error | Unexpected application error during attestation creation |

<a id="error-response-evaluate-policy-scan"></a>

### Evaluate Policy Scan™

Common errors when evaluating policies at `/packages/{type}/{namespace}/{name}/{version}/policy-scans/{scan-name}`:

  
| Status | Problem Type | Scenario |
| --- | --- | --- |
| 400 | bad-request | Missing SHA-256 or repository URL, invalid criteria format |
| 401 | N/A (handled by Spring Security) | Missing or invalid authentication credentials |
| 403 | N/A (handled by Spring Security) | User lacks publish-policy-scans permission for this package/repository |
| 404 | not-found | Policy Scan definition does not exist |
| 429 | rate-limit-exceeded | Too many concurrent requests, connection pool exhausted |
| 500 | external-service-failure | Cannot communicate with Develocity, attestation storage unavailable |
| 500 | internal-server-error | Unexpected error during policy evaluation |

<a id="error-response-fetch-attestation"></a>

### Fetch Attestation

Common errors when retrieving attestations at `/packages/{type}/{namespace}/{name}/{version}/{digestType}:{digest}/attestations/{instance}/{id}`:

  
| Status | Problem Type | Scenario |
| --- | --- | --- |
| 400 | bad-request | Malformed digest format, invalid instance identifier |
| 401 | N/A (handled by Spring Security) | Missing or invalid authentication credentials |
| 403 | N/A (handled by Spring Security) | User lacks read-attestations permission for this package/repository |
| 404 | not-found | Attestation ID does not exist, storage instance not configured |
| 500 | external-service-failure | Cannot connect to S3 or Artifactory storage |
| 500 | internal-server-error | Unexpected error during attestation retrieval |

<a id="best-practices"></a>

## Best Practices

<a id="best-practices-client-implementation"></a>

### Client Implementation

When consuming the Develocity Provenance Governor API, follow these best practices for error handling:

1.  **Always Check HTTP Status Codes:** Inspect the status code before parsing the response body.
    
2.  **Parse Problem Detail Responses:** For 4xx and 5xx responses, parse the RFC 7807 Problem Detail JSON to get structured error information.
    
3.  **Implement Retry Logic:** For 429 (rate limit) and 500-level errors, implement exponential backoff retry logic:
    
    ```bash
    #!/bin/bash
    max_retries=5
    retry_count=0
    wait_time=1
    
    while [ $retry_count -lt $max_retries ]; do
      response=$(curl -s -w "\n%{http_code}" -X POST \
        "https://provenance-governor.example.com/packages/maven/com.example/acme-app/1.0.0/policy-scans/build" \
        -H "Authorization: Basic \${AUTH_TOKEN}" \
        -H "Content-Type: application/json" \
        -d '{"sha256":"...","repositoryUrl":"..."}')
    
      status_code=$(echo "$response" | tail -n1)
      body=$(echo "$response" | head -n-1)
    
      if [ "$status_code" -eq 200 ]; then
        echo "Success: $body"
        exit 0
      elif [ "$status_code" -eq 429 ] || [ "$status_code" -ge 500 ]; then
        echo "Error $status_code, retrying in \${wait_time}s..."
        sleep $wait_time
        wait_time=$((wait_time * 2))
        retry_count=$((retry_count + 1))
      else
        echo "Client error $status_code: $body"
        exit 1
      fi
    done
    
    echo "Max retries exceeded"
    exit 1
    ```
    
4.  **Log Error Details:** Log the full problem detail response for debugging, including `detail`, `instance`, and any additional properties.
    
5.  **Handle Specific Error Types:** Implement specific handling for different problem types based on your use case.
    

<a id="monitoring"></a>

### Monitoring

Set up monitoring and alerting for API errors:

*   **Monitor 5xx Error Rates:** High rates of 500-level errors indicate service health issues.
    
*   **Track 429 Responses:** Frequent rate limiting suggests the need for scaling or request optimization.
    
*   **Alert on Repeated Failures:** Configure alerts for sustained error conditions.
    
*   **Log Analysis:** Regularly review application logs for error patterns and trends.
    

```bash
# Example: Query application logs for errors
kubectl logs deployment/api -n develocity-provenance-governor \
  --since=1h | grep -E "ERROR|WARN|Problem Detail"
```

<a id="related-documentation"></a>

## Related Documentation

*   [API Reference](https://docs.gradle.com/develocity/provenance-governor/1.6/api-reference/) - Complete API endpoint documentation
    
*   [Policy Configuration](https://docs.gradle.com/develocity/provenance-governor/1.6/app-config-policies/) - Configure access control and Policy Scan definitions
    
*   [Troubleshooting Guide](https://docs.gradle.com/develocity/provenance-governor/1.6/troubleshooting/) - General troubleshooting steps
    
*   [RFC 7807 Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807) - Official RFC specification