Skip to main content

insufficient_scope

The key is valid and the workspace was identified, but the permission this endpoint requires is not on it. Nothing was sent and nothing was charged.

Status: 403

{
  "status": 403,
  "type": "insufficient_scope",
  "message": "This API key does not have the 'sending' permission",
  "request_id": "req_01J8K2P...",
  "doc_url": "https://docs.epostix.com/errors/insufficient_scope"
}

The scope quoted in message is the one the endpoint asked for.

Why you got this​

  • The key was created with a narrow scope set. Sending a message needs sending, reading one back needs emails:read.
  • The endpoint needs a management scope the key never had, such as domains:manage, contacts:manage, webhooks:manage or suppressions:manage.
  • You are creating a key with permissions the calling key does not hold. That request is refused with Cannot create a key with more permissions than the current key.

How to fix it​

Call the endpoint with a key that carries the scope named in message. Scopes are fixed when a key is created, so grant the permission on a new key rather than trying to widen an existing one.

To mint keys for other services, the calling key needs api-keys:manage plus every scope it hands out. A key with * can create any key; a key with sending alone can only create another sending key. Authentication lists the full scope set.

Is it safe to retry​

No, not with the same key. The permission check is deterministic and refuses it again. Retry with a key that holds the scope. Nothing was created, so no duplicate can result.