Error Codes

Error response format, error codes, and troubleshooting guide for CRAFT APIs.

Error Codes

All CRAFT APIs return consistent error responses. This page documents the error format, all error codes, and troubleshooting guidance for each.

Error Response Format

Error responses follow a standard JSON structure:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Agent with ID '550e8400-e29b-41d4-a716-446655440000' not found.",
    "status": 404,
    "details": {
      "resource_type": "artifact",
      "resource_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "request_id": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Field	Type	Description
code	string	Machine-readable error code
message	string	Human-readable error description
status	integer	HTTP status code
details	object	Additional context (varies by error type)
request_id	string	Unique request identifier for support
trace_id	string	OpenTelemetry trace ID for end-to-end debugging

HTTP Status Codes

Status	Meaning	When Returned
400	Bad Request	Invalid request body, missing required fields, malformed parameters
401	Unauthorized	Missing, expired, or invalid JWT token
403	Forbidden	Valid token but insufficient permissions
404	Not Found	Resource does not exist or is not accessible
409	Conflict	Resource already exists or version conflict
422	Unprocessable Entity	Request is well-formed but semantically invalid
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service (Keycloak, OpenFGA) unavailable
503	Service Unavailable	Service is starting up or shutting down

Error Codes Reference

The OpenAPI specifications define a base ErrorCode enum with 9 values: INVALID_REQUEST, INVALID_TOKEN, INSUFFICIENT_PERMISSIONS, RESOURCE_NOT_FOUND, RESOURCE_ALREADY_EXISTS, VALIDATION_ERROR, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE, INTERNAL_ERROR. The implementation may return more specific codes within each category as documented below.

Authentication Errors (401)

Code	Message	Troubleshooting
UNAUTHENTICATED	No authentication token provided	Include Authorization: Bearer <token> header
TOKEN_EXPIRED	Access token has expired	Refresh the token or obtain a new one
TOKEN_INVALID	Token signature verification failed	Ensure the token was issued by the correct Keycloak realm
TOKEN_MALFORMED	Token format is invalid	Check that the token is a valid JWT (three base64-encoded segments separated by dots)

Authorization Errors (403)

Code	Message	Troubleshooting
FORBIDDEN	Insufficient permissions for this operation	Check your role assignment on the target project; see RBAC Configuration
PROJECT_ACCESS_DENIED	No access to the specified project	Verify the project ID in the request matches a project you have been granted access to
ORG_ACCESS_DENIED	Token does not belong to this organization	Authenticate against the correct Keycloak realm for the target organization

Resource Errors (404, 409)

Code	Message	Troubleshooting
RESOURCE_NOT_FOUND	Resource not found	Verify the resource ID and ensure you have can_read permission
RESOURCE_ALREADY_EXISTS	Resource with this identifier already exists	Use a unique name or identifier; use PUT to update existing resources
VERSION_CONFLICT	Resource has been modified by another request	Re-fetch the resource and retry with the current version

Validation Errors (400, 422)

Code	Message	Troubleshooting
VALIDATION_ERROR	Request body validation failed	Check the details field for specific field-level errors
INVALID_PARAMETER	Invalid query parameter	Verify parameter name, type, and allowed values
MISSING_REQUIRED_FIELD	Required field is missing	Include all required fields in the request body
INVALID_FORMAT	Field value format is invalid	Check the expected format (UUID, URL, email, etc.)
SEARCH_QUERY_INVALID	Malformed search query	Use plain text for search queries; special operators are reserved

Rate Limiting Errors (429)

Code	Message	Troubleshooting
RATE_LIMIT_EXCEEDED	Rate limit exceeded	Wait for the Retry-After header duration; implement exponential backoff
QUOTA_EXCEEDED	Tenant quota exceeded	Contact your administrator to increase the quota for the exceeded dimension

Server Errors (500, 502, 503)

Code	Message	Troubleshooting
INTERNAL_ERROR	An unexpected error occurred	Retry the request; if persistent, report with request_id and trace_id
UPSTREAM_UNAVAILABLE	Upstream service is unavailable	Keycloak or OpenFGA may be down; check service health. Governance down causes Assets/Utils to return 403
SERVICE_STARTING	Service is initializing	Wait for the service to complete startup; check readiness probe
DATABASE_ERROR	Database operation failed	Retry the request; if persistent, check database connectivity

Handling Errors in Code

Python

from em_runtime_assets_sdk import AssetsClient, ApiError

client = AssetsClient(base_url="https://<host>:8002", token=token)

try:
    agent = await client.artifacts.get(artifact_uri)
except ApiError as e:
    if e.status == 401:
        # Token expired -- refresh and retry
        token = await refresh_token()
        client.token = token
        agent = await client.artifacts.get(artifact_uri)
    elif e.status == 404:
        print(f"Agent not found: {e.error.message}")
    elif e.status == 429:
        # Rate limited -- wait and retry
        await asyncio.sleep(e.retry_after)
        agent = await client.artifacts.get(artifact_uri)
    else:
        print(f"Error {e.error.code}: {e.error.message}")
        print(f"Request ID: {e.error.request_id}")
        raise

TypeScript

import { AssetsClient, ApiError } from '@emergence/em-runtime-assets-sdk';

const client = new AssetsClient({
  baseUrl: 'https://<host>:8002',
  token: accessToken
});

try {
  const agent = await client.agents.get(agentId);
} catch (error) {
  if (error instanceof ApiError) {
    switch (error.status) {
      case 401:
        // Refresh token and retry
        break;
      case 404:
        console.log(`Agent not found: ${error.error.message}`);
        break;
      case 429:
        // Wait for retry-after and retry
        await sleep(error.retryAfter * 1000);
        break;
      default:
        console.error(`Error ${error.error.code}: ${error.error.message}`);
        console.error(`Request ID: ${error.error.requestId}`);
    }
  }
}

cURL

# Check the HTTP status code
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://<host>:8002/assets/artifacts/$ARTIFACT_URI")

if [ "$HTTP_STATUS" -eq 401 ]; then
  echo "Token expired, refreshing..."
  TOKEN=$(refresh_token)
elif [ "$HTTP_STATUS" -eq 404 ]; then
  echo "Agent not found"
elif [ "$HTTP_STATUS" -eq 429 ]; then
  echo "Rate limited, waiting..."
  sleep 60
fi

Retry Strategy

For transient errors (429, 500, 502, 503), implement exponential backoff with jitter:

Attempt	Wait Time	Max Wait
1st retry	1 second + jitter	2 seconds
2nd retry	2 seconds + jitter	4 seconds
3rd retry	4 seconds + jitter	8 seconds
4th retry	8 seconds + jitter	16 seconds
Max retries	5	30 seconds

For 429 errors, always respect the Retry-After header rather than using exponential backoff. The header provides the exact wait time until the rate limit window resets.

Getting Help

When reporting an issue, include:

1. The request_id from the error response
2. The trace_id for end-to-end correlation
3. The timestamp of the request
4. The full error response body

Next Steps

API Overview

Review the full API structure and endpoints.

API Authentication

Learn how to obtain and manage JWT tokens.

Python SDK

Use the Python SDK with built-in error handling.

TypeScript SDK

Use the TypeScript SDK with built-in error handling.