API Error Reference

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 standard.

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.

Problem Detail Format

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

{
  "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/my-app/1.0.0/attestations"
}

Standard Fields

Field Description

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:<category>`.
`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).

type

A URI reference that identifies the problem type. For Develocity Provenance Governor, these follow the pattern urn:gradle:develocity:provenance-governor:problems:<category>.

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).

Optional Fields

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

Field Description

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.

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.

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

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

Bad Request (400)

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

HTTP Status: 400 Bad Request

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.

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

Example: Invalid Repository URL

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-app/1.0.0/attestations"
}

Example: Unsupported Package Type

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

Response:

{
  "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/my-package/1.0.0/attestations"
}

Example: Missing Required Fields

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

Response:

{
  "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/my-app/1.0.0/policy-scans/build"
}

Troubleshooting

Error Message Pattern Solution

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)

"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)

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

Not Found (404)

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

HTTP Status: 404 Not Found

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.

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

Example: Policy Scan Not Found

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-app/1.0.0/policy-scans/production-gate"
}

Example: Attestation Not Found

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

Response:

{
  "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/my-app/1.0.0/sha256:73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497/attestations/s3:prod/nonexistent-uuid"
}

Troubleshooting

Error Message Pattern Solution

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.

"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.

Checking Available Policy Scans: To list all configured policy scan definitions:

kubectl get configmap policies -n develocity-provenance-governor -o yaml

Look for resources with kind: PolicyScanDefinition in the ConfigMap data.

Rate Limit Exceeded (429)

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

HTTP Status: 429 Too Many Requests

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.

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

Example

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-app/1.0.0/policy-scans/build"
}

Troubleshooting

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:

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

External Service Failure (500)

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

HTTP Status: 500 Internal Server Error

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.

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

Example: Develocity Unreachable

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-app/1.0.0/attestations"
}

Example: Build Event Retrieval Error

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-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"
  }
}

Example: Partial Storage Failure

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-app/1.0.0/attestations",
  "request": {
    "packageCoordinates": "pkg:maven/com.example/my-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"
    }
  ]
}

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.

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:

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

Check S3 connectivity:

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

Review application logs for detailed error messages:

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

Internal Server Error (500)

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

HTTP Status: 500 Internal Server Error

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.

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

Example

curl --request POST \
  --url https://provenance-governor.example.com/packages/maven/com.example/my-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:

{
  "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/my-app/1.0.0/policy-scans/build"
}

Troubleshooting

When you receive this error:

Check Application Logs: Review the logs for stack traces and error details:

kubectl logs deployment/api -n develocity-provenance-governor --tail=200

Verify Configuration: Check that all ConfigMaps and Secrets are properly formatted:

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

Check Resource Usage: Verify the pod has sufficient memory and CPU:

kubectl top pod -n develocity-provenance-governor
kubectl describe pod -n develocity-provenance-governor -l app=api

Review Recent Changes: If the error started occurring recently, review any configuration or policy changes.
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

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.

Error Response Examples by Endpoint

Publish Attestations

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

Status Problem Type Scenario

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

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

Evaluate Policy Scan

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

Status Problem Type Scenario

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

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

Fetch Attestation

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

Status Problem Type Scenario

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

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

Best Practices

Client Implementation

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

Always Check HTTP Status Codes: Inspect the status code before parsing the response body.
Parse Problem Detail Responses: For 4xx and 5xx responses, parse the RFC 7807 Problem Detail JSON to get structured error information.

Implement Retry Logic: For 429 (rate limit) and 500-level errors, implement exponential backoff retry logic:

#!/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/my-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

Log Error Details: Log the full problem detail response for debugging, including detail, instance, and any additional properties.
Handle Specific Error Types: Implement specific handling for different problem types based on your use case.

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.

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

API Error Reference

Overview

Problem Detail Format

Standard Fields

Optional Fields

Problem Types

Bad Request (400)

Description

Common Causes

Example: Invalid Repository URL

Example: Unsupported Package Type

Example: Missing Required Fields

Troubleshooting

Not Found (404)

Description

Common Causes

Example: Policy Scan Not Found

Example: Attestation Not Found

Troubleshooting

Rate Limit Exceeded (429)

Description

Common Causes

Example

Troubleshooting

External Service Failure (500)

Description

Common Causes

Example: Develocity Unreachable

Example: Build Event Retrieval Error

Example: Partial Storage Failure

Troubleshooting

Internal Server Error (500)

Description

Common Causes

Example

Troubleshooting

Error Response Examples by Endpoint

Publish Attestations

Evaluate Policy Scan

Fetch Attestation

Best Practices

Client Implementation

Monitoring

Related Documentation