Errors

Every error the token endpoint, the resource API and the treasury endpoint return, what causes it, and what to do next.

There are two error envelopes. The token endpoint uses the OAuth shape. Everything else uses the resource shape.

Token errors

POST /api/partner/oauth/token returns a flat OAuth error:

{ "error": "invalid_client" }

HTTP	Error	Cause	What to do
400	invalid_request	Malformed form body, both HTTP Basic and form credentials sent, or a repeated parameter	Send credentials one way only
400	unsupported_grant_type	grant_type is not client_credentials	Fix the parameter
400	invalid_scope	Requested scope is not a subset of your entitlements	Drop the extra scopes, or ask Glide to widen your entitlements
401	invalid_client	Unknown client or wrong secret. WWW-Authenticate: Basic realm="glide-partner" is set, and both cases return identical bodies	Check the credentials. Ask Glide to rotate if the secret is lost
403	invalid_client	Valid credentials on a suspended or pending client	Contact Glide. Retrying will not help
429	rate_limited	Over 30 issuances a minute, including failed attempts. Retry-After: 60	Cache your token. See Authentication
503	temporarily_unavailable	Signing or audit persistence is unavailable, so Glide withheld the token	Retry with backoff

Resource errors

Every other endpoint returns:

{
  "error": {
    "code": "grant_required",
    "message": "An active user grant and token scope are required",
    "request_id": "33333333-3333-4333-8333-333333333333"
  }
}

request_id matches the X-Request-Id response header and the audit row for the call. Log it. It is the fastest way for Glide support to find what happened.

HTTP	Code	Cause	What to do
400	invalid_request	Failed schema validation, an unknown body field, or a bad query parameter	Validate against the contract before sending
400	invalid_json	The body is not parseable JSON	Check serialization and Content-Type
400	invalid_cursor	The cursor is malformed or no longer valid	Restart paging from your saved since watermark
401	invalid_token	Missing, expired or unverifiable bearer. WWW-Authenticate: Bearer is set	Drop the cached token and mint once. Do not loop
403	grant_required	The user’s grant is absent, revoked or too narrow, or your token lacks the scope	Send the user back through consent, or ask Glide to widen your entitlements
403	partner_inactive	Your partner record is suspended	Contact Glide
403	user_inactive	The user’s account is not active	Stop paying that user until it is resolved
404	user_not_found	No pre-creation receipt and no grant for your partner, including an id that belongs only to another partner	Pre-create the user, or check the id
409	kyc_provider_conflict	The user already has verification with a different provider	Do not retry. Partners cannot switch a user’s provider
413	body_too_large	Over 4096 bytes on pre-create, or over 64 KiB on a treasury batch	Split the request
429	rate_limited	Over the per-operation limit. Retry-After: 60	Back off for the full window
500	internal_error	Unhandled server error	Retry idempotent calls with the same ids
503	auth_unavailable	Glide’s token verification key configuration is missing or malformed	Retry with backoff and alert Glide if it persists
503	audit_unavailable	Glide could not persist the audit record	Retry. A read is withheld rather than served unaudited
503	provider_unavailable	An upstream provider is unusable, including a rejected sandbox verification URL	Retry with backoff

A 503 from audit_unavailable after a successful pre-create is safe to retry. Pre-creation is idempotent per partner and email, so the retry returns the same user_id and the same created value.

Treasury errors

The treasury batch endpoint uses the same envelope with additional codes.

HTTP	Code	Cause	What to do
403	treasury_inactive	The treasury is suspended or disabled, or its mandate expired	Ask Glide to reactivate, then retry the same execution ids
403	payer_not_allowed	payer_entity_id does not match your binding	Fix your configured payer id. Do not guess another
403	policy_denied	A configured cap or the step-up amount was exceeded	Reduce the batch, or ask Glide to raise the cap. No token bypasses this
404	treasury_not_configured	No treasury is bound to your partner	Complete binding and funding with Glide
409	insufficient_funds	The available treasury balance is below the new total	Fund the reserve, have Glide record it, then retry the same ids
409	idempotency_conflict	The same Idempotency-Key was reused with a different request, including a different item order	Investigate the original batch. Do not change the ids to force it through
409	execution_conflict	A reused execution_id changed its recipient, payer, payout_id, amount, currency or reference	Investigate. No item in the batch executed

Cap errors name the limit they violated. They deliberately do not reveal how much allowance remains.

Retry rules that matter for money

A timeout, a dropped connection, a 5xx or an unparseable response from the treasury endpoint is unconfirmed, not failed. Retry the identical body with the identical Idempotency-Key. Never mark the payout failed and never mint replacement execution ids on an unconfirmed outcome.

Outcome	Safe to retry with the same ids	Notes
Timeout or connection loss	Yes	A replayed 200 returns the original body
500, 503	Yes	Same key, same payload
429	Yes, after Retry-After	Nothing executed
400, 413	No, fix the request first	Nothing executed and no ids were consumed
403 policy_denied, treasury_inactive, grant_required	Yes, after the underlying condition is fixed	Nothing executed
409 insufficient_funds	Yes, after funding is recorded	Nothing executed
409 idempotency_conflict, execution_conflict	No, investigate first	Signals a bug in your id handling or a mutated request

A validation, policy or funds rejection is audited and consumes no execution ids, so your obligations stay payable once the cause is fixed.