What does 403 insufficient_scope mean on the Model API?

The key is valid, but it doesn't have the models:invoke permission the Model API needs.

Code: insufficient_scope · HTTP status: 403

Keys carry permissions. A key made only for the Agent API (runs:write, runs:read) or for reading your balance (account:read) can't call models.

Common causes#

• a key created with an Agent API preset
• a read-only key reused for model calls

How to fix it#

1. Create a key with the Model API preset (permission models:invoke) in Console › API keys.
2. Keep separate keys per job; that's easier to audit and revoke.

Should my code retry?#

Not retryable with the same key.

The error body uses the OpenAI shape, so OpenAI SDKs raise it as an exception you can catch:

{"error": {"message": "...", "type": "...", "code": "insufficient_scope", "param": null}}

Every response also carries an X-Request-Id. Keep it in your logs; it's the quickest way for support to find a request.

See the full list in the Model API reference.

Still need help?#

• General support: support@clatterlabs.com or team@clatterlabs.xyz
• Infrastructure questions, or permanent deletion of your data (your whole account or one service): infrastructure@clatterlabs.xyz

We usually reply within the first hour, and always within 24 hours. A full support team is with you.