Troubleshooting and FAQ¶

Common issues, error codes, and solutions for the Fermi API.

Common Issues¶

Invalid API Key Errors¶

Error Message:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solutions:

1. Verify your API key is correct
2. Check if the key has been revoked
3. Check expiration date
4. Ensure header format: Authorization: Bearer <api-key>

Example:

# Wrong
curl -H "Authorization: fmk_live_abc123" ...

# Correct
curl -H "Authorization: Bearer fmk_live_abc123" ...

Missing Scope Errors¶

Error Message:

{
  "error": "Forbidden",
  "message": "Missing required scope: analytics:query"
}

Solutions:

1. Create a new API key with the required scope
2. Rotate your existing API key to add the scope
3. Update service actor capabilities

Scopes Reference

Token Expiration Issues¶

Error Message:

{
  "error": "Unauthorized",
  "message": "JWT verification failed - token is invalid or expired"
}

Solutions:

1. Exchange for a new token using the token exchange endpoint
2. Implement automatic token refresh
3. Cache tokens until near expiration

Example:

import requests

def get_valid_token(api_key, service_actor_id):
    """Exchange for new token"""
    response = requests.post(
        "https://api.fermi.dev/public/v1/identity/auth/token/exchange",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"serviceActorId": service_actor_id}
    )
    response.raise_for_status()
    return response.json()["token"]

Rate Limiting¶

Error Message:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Solutions:

1. Implement exponential backoff
2. Cache responses when appropriate
3. Reduce request frequency
4. Monitor rate limit headers

Example:

import time

def make_request_with_backoff(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            wait_time = retry_after * (2 ** attempt)
            time.sleep(wait_time)
            continue

        return response

Network Connectivity¶

Error Message:

ConnectionError: Failed to connect to api.fermi.dev

Solutions:

1. Check your internet connection
2. Verify firewall rules allow outbound HTTPS
3. Test DNS resolution: nslookup api.fermi.dev

Service Actor Not Found¶

Error Message:

{
  "status": 404,
  "message": "Service actor not found"
}

Solutions:

1. Verify the service actor ID
2. List service actors to find the correct ID
3. Ensure service actor belongs to your organization

Organization Mismatch¶

Error Message:

{
  "status": 403,
  "message": "Service actor's parent organisation must match API key's organization"
}

Solutions:

1. Verify organization IDs match
2. Create service actor in the correct organization
3. Use API key from the same organization

Error Codes Reference¶

Frequently Asked Questions¶

How do I reset my API key?¶

You cannot "reset" an API key, but you can:

1. Rotate the key to get a new key value
2. Create a new API key
3. Revoke the old key if compromised

What scopes do I need?¶

Required scopes depend on what you want to do:

• Query analytics: analytics:query
• Read analytics: analytics:read
• Write analytics: analytics:write
• Create service actors: provision:service:create
• Exchange tokens: provision:token:exchange

Scopes Reference

How long do tokens last?¶

Service actor tokens expire after 15 minutes (900 seconds).

How do I handle rate limits?¶

1. Monitor rate limit headers in responses
2. Implement exponential backoff when you hit limits
3. Cache responses when appropriate
4. Reduce request frequency if possible
5. Use pagination for large data sets

Can I use multiple API keys?¶

Yes! You can create multiple API keys for different purposes:

• Different applications or use cases
• Different permission levels

How do I know if my API key is working?¶

List service actors (API key, not a service-actor token):

curl -X GET https://api.fermi.dev/public/v1/identity/service-actors \
  -H "Authorization: Bearer fmk_live_your_api_key"

After token exchange, list chat sessions:

curl -X GET https://api.fermi.dev/agents-service/api/v1/agentcore/sessions \
  -H "Authorization: Bearer <service-actor-token>"

There is no GET /public/v1/analytics/status endpoint (live 405).

What's the difference between API keys and tokens?¶

• API Keys: Credentials for creating organizations and service actors
• Tokens: Short-lived JWTs (15 minutes) for accessing data

Use API keys to create organizations and service actors. Use service actor tokens to access data.

How do I update my API key scopes?¶

You can update scopes by rotating your API key:

curl -X POST https://api.fermi.dev/public/v1/identity/api-keys/{key-id}/rotate \
  -H "Authorization: Bearer <user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["analytics:query", "analytics:read", "analytics:write"]
  }'

What happens if I lose my API key?¶

If you lose your API key:

1. Revoke the lost key immediately
2. Create a new API key
3. Update your applications with the new key

Important: API keys are only shown once when created. If you lose it, you must create a new one.

404 on /public/v1/analytics/query¶

That path does not exist. Ask Fermi with:

POST https://api.fermi.dev/agents-service/api/v1/agentcore/chat/stream and { "message", "session_id" }.

Token exchange is POST /public/v1/identity/auth/token/exchange (not tokens/exchange).

How do I test my integration?¶

1. Test with simple endpoints first (GET /public/v1/identity/service-actors, then GET .../agentcore/sessions)
2. Verify authentication works
3. Test error handling
4. Test all endpoints before deploying

Getting Help¶

If you're still experiencing issues:

1. Check the documentation

   • API Reference
   • Authentication Guide
   • Code Examples

2. Review error messages carefully

   • Error messages often contain specific guidance
   • Check status codes and error details

Next Steps¶

• API Reference - Complete endpoint documentation
• Authentication Guide - Authentication methods
• Code Examples - Working examples