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
`412`	Precondition Failed	`If-Match` provided but does not match current resource version (PUT)
`413`	Payload Too Large	Uploaded body exceeds the server’s size limit (artifact upload)
`422`	Unprocessable Entity	Request is well-formed but semantically invalid
`428`	Precondition Required	PUT without `If-Match` header (concurrency control required)
`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
TypeScript
cURL

from em_runtime_assets_sdk import AuthenticatedClient
from em_runtime_assets_sdk.api.artifacts import get_artifact
from em_runtime_assets_sdk.errors import UnexpectedStatus

client = AuthenticatedClient(
    base_url="https://<platform-host>/api/assets",
    token=token,
)

try:
    agent = await get_artifact.asyncio(client=client, artifact_uri=artifact_uri)
except UnexpectedStatus as e:
    if e.status_code == 401:
        # Token expired -- refresh and rebuild the client (token is immutable).
        token = await refresh_token()
        client = AuthenticatedClient(
            base_url="https://<platform-host>/api/assets", token=token
        )
        agent = await get_artifact.asyncio(client=client, artifact_uri=artifact_uri)
    elif e.status_code == 404:
        print(f"Not found: {e.content!r}")
    elif e.status_code == 429:
        # Rate limited -- read Retry-After from response headers
        retry_after = int(e.response.headers.get("Retry-After", "1"))
        await asyncio.sleep(retry_after)
        agent = await get_artifact.asyncio(client=client, artifact_uri=artifact_uri)
    else:
        print(f"HTTP {e.status_code}: {e.content!r}")
        raise

UnexpectedStatus.content is raw bytes; decode and json.loads() to read the envelope ({"error": {"code", "message", "request_id"}}).

import { Client, ApiError } from '@emergence-ai/em-runtime-assets-sdk';
import { getArtifact } from '@emergence-ai/em-runtime-assets-sdk/api';

const client = new Client({
  BASE: 'https://<platform-host>/api/assets',
  TOKEN: accessToken,
});

try {
  const agent = await getArtifact({ client, artifactUri });
} catch (error) {
  if (error instanceof ApiError) {
    const body = error.body as
      | { error?: { code?: string; message?: string; request_id?: string } }
      | undefined;
    switch (error.status) {
      case 401:
        // Token expired -- refresh and rebuild the client
        break;
      case 404:
        console.log(`Not found: ${body?.error?.message}`);
        break;
      case 429: {
        const retryAfter = Number(error.headers?.['retry-after'] ?? '1');
        await sleep(retryAfter * 1000);
        break;
      }
      default:
        console.error(`HTTP ${error.status} (${body?.error?.code}): ${body?.error?.message}`);
        console.error(`Request ID: ${body?.error?.request_id}`);
    }
  }
}

# Check the HTTP status code
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://<platform-host>/api/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:

The request_id from the error response
The trace_id for end-to-end correlation
The timestamp of the request
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.

Overview

Platform APIs

Solution APIs

SDKs & Client Libraries

Error Codes

Error Codes

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors (401)

Authorization Errors (403)

Resource Errors (404, 409)

Validation Errors (400, 422)

Rate Limiting Errors (429)

Server Errors (500, 502, 503)

Handling Errors in Code

Retry Strategy

Getting Help

Next Steps

API Overview

API Authentication

Python SDK

TypeScript SDK

​Error Codes

​Error Response Format

​HTTP Status Codes

​Error Codes Reference

​Authentication Errors (401)

​Authorization Errors (403)

​Resource Errors (404, 409)

​Validation Errors (400, 422)

​Rate Limiting Errors (429)

​Server Errors (500, 502, 503)

​Handling Errors in Code

​Retry Strategy

​Getting Help

​Next Steps

API Overview

API Authentication

Python SDK

TypeScript SDK

Error Codes

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors (401)

Authorization Errors (403)

Resource Errors (404, 409)

Validation Errors (400, 422)

Rate Limiting Errors (429)

Server Errors (500, 502, 503)

Handling Errors in Code

Retry Strategy

Getting Help

Next Steps