ARCP Problem Details Reference¶

This directory contains documentation for all problem types that can be returned by the ARCP API. These problems follow the RFC 9457 Problem Details for HTTP APIs standard.

Problem Types by Category¶

🤖 Agent Problems¶

• Agent Not Found - Requested agent does not exist
• Agent Not Available - Agent exists but is not reachable
• Duplicate Agent - Agent ID already exists during registration
• Agent Registration Failed - Agent registration process failed

🔐 Authentication Problems¶

• Authentication Failed - Login credentials are invalid
• Token Invalid/Expired - JWT token is invalid or expired
• Session Invalid - Session validation failed
• Session Expired - Session has timed out

🛡️ Authorization Problems¶

• Insufficient Permissions - User lacks required permissions
• Forbidden - Access to resource is forbidden

🔢 PIN Problems¶

• PIN Required - PIN verification is required
• PIN Already Set - PIN has already been configured
• PIN Not Set - PIN must be set before use
• PIN Incorrect - Provided PIN is wrong
• PIN Invalid Length - PIN does not meet length requirements

⚙️ Configuration Problems¶

• Configuration Error - Service configuration issue

🔧 Service Problems¶

• Vector Search Unavailable - Search service is down
• Operation Timeout - Operation exceeded time limit
• Connection Timeout - Network connection timed out
• Endpoint Unreachable - Target endpoint cannot be reached

✅ Validation Problems¶

• Validation Failed - Request data validation failed
• Invalid Input - Input data format is incorrect
• Required Header Missing - Required HTTP header is missing
• Invalid URL - URL format is invalid

🚦 Rate Limiting Problems¶

• Rate Limit Exceeded - Too many requests from client

📦 Request Size Problems¶

• Request Too Large - Request body exceeds size limit
• Headers Too Large - Request headers exceed size limit

🔧 Generic Problems¶

• Internal Error - Internal server error occurred
• Request Error - General request processing error
• Not Found - Requested resource was not found

Problem Details Format¶

All ARCP problems follow this structure:

{
  "type": "https://arcp.0x001.tech/docs/problems/{problem-type}",
  "title": "Human Readable Title",
  "status": 400,
  "detail": "Specific details about this occurrence",
  "instance": "/request/path",
  "timestamp": "2024-01-01T12:00:00Z",
  "request_id": "req_12345"
}

Using Problem Details¶

In Client Applications with ARCP¶

When using the ARCP client, errors are automatically handled and converted to appropriate exceptions:

import asyncio
from arcp import ARCPClient, ARCPError, AuthenticationError, RegistrationError

async def error_handling_example():
    async with ARCPClient("https://arcp.example.com") as client:
        try:
            # This might fail if agent doesn't exist
            agent = await client.get_agent("missing-agent")

        except ARCPError as e:
            # ARCP client automatically parses problem details
            print(f"ARCP Error: {e}")

            # You can check for specific error types
            if "not found" in str(e).lower():
                print("Agent not found - handle missing agent scenario")
            elif "authentication" in str(e).lower():
                print("Authentication required - handle login")

        try:
            # Agent registration example
            agent_info = await client.register_agent(
                agent_id="my-agent",
                name="My Agent",
                # ... other required parameters
            )

        except AuthenticationError:
            print("Authentication failed - check credentials")
        except RegistrationError as e:
            print(f"Registration failed: {e}")
        except ARCPError as e:
            print(f"General ARCP error: {e}")

if __name__ == "__main__":
    asyncio.run(error_handling_example())

For Troubleshooting¶

1. Check the exception type - ARCP client maps problems to specific exceptions
2. Read the exception message - Contains the problem detail information
3. Note the timestamp - Helps correlate with server logs
4. Use the request_id - Reference when contacting support

Base URI¶

All ARCP problem types use the base URI:

https://arcp.0x001.tech/docs/problems/

This documentation is accessible at that base URL for programmatic problem resolution.