Troubleshooting

client returns 401

Check:

• whether the request includes Authorization: Bearer <user_token>
• whether the token has expired
• whether City has DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY configured
• whether the token was issued by the current Federation
• whether the Token's bureau_id belongs to the current product

client returns 403

Check:

• whether the Bureau bound to the token has been paused
• whether the target Bureau was active when the admin side issued the token

client returns 404

Check:

• whether the HTTP route is correct
• whether the target service has been registered in City
• whether the target Bureau existed when the admin side issued the token

model not found or handler not hit

Check:

• whether the client-provided model has been registered through AIChannel.model() + AIService.use()
• whether the target model includes the required action for the current pathway, such as text, stream, or image
• whether the request included the intended model id
• whether city.ai.catalog() can see the model

These cases usually return 422.

City returns 500

Check:

• whether City has DOWNCITY_FEDERATION_TOKEN_SIGNING_KEY and a provisioned administrator account
• whether the target service has a registered handler
• whether the handler or provider call threw an error without statusCode
• whether the onError hook recorded the original error

provider call failed

Check:

• whether the matching key exists in City .env
• whether the handler reads the correct input.env() key
• whether model meta matches the current provider calling style

usage not recorded

Check:

• whether AIService and CreditsService are mounted before UsageService and supplied as its readers
• whether the AI provider returned final RuntimeMetering; executions without final metering only increase the execution count
• whether the Credits transaction is an applied positive charge; top-ups, failed, and pending transactions are excluded
• whether the query supplies real ordered from and to dates plus a valid IANA timezone