Skip to main content
The Trench Partner API returns standardized error responses so you can handle failures consistently. Every error is JSON and carries a stable error code, which is what you should match on. The message field is written for humans and may change without notice.

Error Response Format

Code-specific fields are additive, so we recommend handling their absence rather than assuming they are present.

Auth and Access

Handle 401 invalid_token by refreshing once and then re-authorizing if that fails. Retrying in a loop or refreshing concurrently for the same user can leave you replaying a rotated-out refresh token, which revokes the entire connection.
Never retry a 401 invalid_client. Twenty failed authentications against one client_id within five minutes lock the app out entirely, so a stale API key in a retry loop will take your working traffic down with it. Treat it as a configuration problem to fix rather than a transient failure.

Trading

The three migration codes describe one sequence. A token leaves the bonding curve, spends a short period in migration_pending while the Raydium pool is created, and may briefly return pool_not_open before trading resumes. All three clear on their own, so retrying after a delay is the right response.You do not need to route migrated tokens elsewhere yourself. The trade endpoints resolve the venue per request and execute against the pool once migration completes.

Governance

Metadata and Mutability

A stale_content_revision response means another proposal landed while your user was editing. Re-read GET /partner/v1/governance/{mint}, rebase the change set onto the new contentRevision, and ask the user to confirm before resubmitting.

Validation

The website, twitter, and telegram fields on proposals/update-content are validated separately from the rest of the body, and they are currently the one place where the error contract does not hold.
All six of these currently return 500 with a generic internal body rather than a 400. They are thrown as genuine validation errors but are missing from the server’s error catalog, so they fall through to the default status.This matters because the usual handling strategy treats a 500 as transient and retries it. These failures are permanent, and the same input will fail identically every time, so we recommend validating these three fields on your own side before submitting.
Normalization is strict. The website field must resolve to https:// with a dotted hostname, twitter must reduce to a handle matching [A-Za-z0-9_]{1,15}, and telegram to [A-Za-z0-9_]{5,32}. Bare handles, @handle, and full URLs are all accepted as input and normalized to a canonical URL.

Infrastructure

These errors are transient, and retrying with backoff is appropriate.

Oracle

The SOL price oracle gates operations that price in USD, and all four of these errors are transient.

Error Handling in Code

The most useful way to group these is not by HTTP status but by what you should do next.

Retry Logic

  1. 429 (Rate Limited): wait for the interval in retry-after, then retry. Nothing was submitted on-chain.
  2. 409 (migration_pending, pool_not_open): the token is between venues. Wait a few seconds and retry, since nothing was submitted on-chain.
  3. 500/502 on reads: retry with exponential backoff, up to a fixed attempt ceiling.
  4. 400/401/403/404 and most 422s: do not retry, since the request needs to change first.
  5. Any write endpoint: see the caution below before retrying at all.
We recommend giving the transient branch a hard attempt ceiling, because a 500 is not always genuinely transient, as the link-field case above shows. Without a ceiling, a single malformed twitter value can become an unbounded retry loop against a permanent failure.Write endpoints should not be placed on an automatic retry path at all. The API does not support idempotency keys, so a resent request can execute twice. See Trades for the reconciliation pattern.
A 429 and a 403 daily_cap_exceeded both indicate that you should slow down, but rate limits clear within the minute whereas volume caps reset at 00:00 UTC. We recommend handling them separately.
Trench emits a broader error catalog than this page covers. Codes tied to token launches, creator rewards, referrals, and trader cashback only arise on first-party surfaces and are unreachable through the Partner API. Everything reachable with a partner access token is listed above.