---
title: "Errors | distribution.tech"
description: "Every error code the distribution API and MCP server return, its HTTP status, the body it returns, and what to do next."
canonical: https://distribution.tech/docs/api/errors
generator: md-live-route
generated: 2026-10-19T11:02:50.705Z
---

# Errors | distribution.tech
-   [Getting started](https://distribution.tech/docs)
-   [API reference](https://distribution.tech/docs/api)
-   [MCP and agents](https://distribution.tech/docs/agents)
-   [Changelog](https://distribution.tech/docs/changelog)

Docs

-   Using the API ›

    -   [API reference](https://distribution.tech/docs/api)
    -   [Authentication](https://distribution.tech/docs/api/authentication)
    -   [Scopes](https://distribution.tech/docs/api/scopes)
    -   [Errors](https://distribution.tech/docs/api/errors)

-   Inventory and audience ›

    -   [GET /audience](https://distribution.tech/docs/api/get-audience)
    -   [GET /inventory](https://distribution.tech/docs/api/get-inventory)

-   Creators ›

    -   [GET /creators](https://distribution.tech/docs/api/get-creators)
    -   [GET /creators/{id}](https://distribution.tech/docs/api/get-creators-id)
    -   [POST /creators/{id}/price-request](https://distribution.tech/docs/api/post-creators-id-price-request)

-   Campaigns ›

    -   [GET /campaigns](https://distribution.tech/docs/api/get-campaigns)
    -   [POST /campaigns](https://distribution.tech/docs/api/post-campaigns)
    -   [GET /campaigns/{id}](https://distribution.tech/docs/api/get-campaigns-id)
    -   [PATCH /campaigns/{id}](https://distribution.tech/docs/api/patch-campaigns-id)
    -   [DELETE /campaigns/{id}](https://distribution.tech/docs/api/delete-campaigns-id)
    -   [POST /campaigns/{id}/archive](https://distribution.tech/docs/api/post-campaigns-id-archive)
    -   [POST /campaigns/{id}/creator-guidelines](https://distribution.tech/docs/api/post-campaigns-id-creator-guidelines)

-   Plans ›

    -   [POST /plans/{id}/approve](https://distribution.tech/docs/api/post-plans-id-approve)
    -   [POST /plans/{id}/dates](https://distribution.tech/docs/api/post-plans-id-dates)
    -   [POST /plans/{id}/lines](https://distribution.tech/docs/api/post-plans-id-lines)
    -   [GET /plans/{id}/quote](https://distribution.tech/docs/api/get-plans-id-quote)
    -   [DELETE /plans/{id}/lines/{line\_id}](https://distribution.tech/docs/api/delete-plans-id-lines-line-id)
    -   [POST /plans/{id}/lines/{line\_id}/swap](https://distribution.tech/docs/api/post-plans-id-lines-line-id-swap)

-   Proof and results ›

    -   [GET /evidence](https://distribution.tech/docs/api/get-evidence)
    -   [GET /results](https://distribution.tech/docs/api/get-results)

-   Company context ›

    -   [GET /brain](https://distribution.tech/docs/api/get-brain)

-   Feedback ›

    -   [GET /feedback](https://distribution.tech/docs/api/get-feedback)
    -   [POST /feedback](https://distribution.tech/docs/api/post-feedback)


1.  [distribution](https://distribution.tech/)
2.  / [Docs](https://distribution.tech/docs)
3.  / [API reference](https://distribution.tech/docs/api)
4.  / Errors

Using the API

# Errors

Every error code the distribution API and MCP server return, its HTTP status, the body it returns, and what to do next.

Last updated October 19, 2026

Copy page as markdown [View .md](https://distribution.tech/docs/api/errors.md)

## The error shape

Every error has one shape: a `code`, a `message` a person can read, and `details` with machine-readable facts when there are any.

```json
{
  "error": {
    "code": "mandate_refused",
    "message": "This plan is over the key's monthly cap.",
    "details": { "reason": "over_monthly_cap", "limit_cents": 500000, "requested_cents": 640000, "over_by_cents": 140000, "escalate": true }
  }
}
```

Over MCP the same code, message and details arrive as the tool's error result.

## Codes

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `bad_request` | 400 | A parameter is not valid or not taken; `details.problems` names each field | Fix the named fields and send again |
| `filter_required` | 400 | A creator list named no audience and the brand has none on file | Pass `match`, a `segment`, `q` or a filter |
| `unauthorized` | 401 | No key, an unknown key or a revoked key | Send a live key as `Authorization: Bearer` |
| `forbidden` | 403 | The key lacks the scope this call needs | Add the scope in Developers, or use a key that has it |
| `mandate_refused` | 403 | A write is outside the key's mandate; `details.reason` says which limit | Take it to a person at the brand; do not retry |
| `not_found` | 404 | No campaign, plan, line or creator of yours has that id | Check the id; another brand's ids are never found |
| `method_not_allowed` | 405 | The path does not take that method | Use the method on the endpoint's page |
| `conflict` | 409 | The state does not allow it; `details.reason` says why (`over_budget`, `plan_signed`, `terms_changed`, `already_priced` and others) | Read the reason: quote again, remove a creator, or pick another action |
| `idempotency_conflict` | 409 | The same `Idempotency-Key` was used with a different body | Use a new key for a new request |
| `in_progress` | 409 | The first request with this `Idempotency-Key` is still running | Wait `Retry-After` seconds and retry with the same key |
| `unprocessable` | 422 | The body is readable but a value cannot be used; `details.problems` names each | Fix the named values |
| `rate_limited` | 429 | Over a limit; `details.reason` and `Retry-After` say which and for how long | Wait `Retry-After` seconds; pace by the RateLimit headers |
| `internal` | 500 | The request failed on our side | Retry with the same `Idempotency-Key` |
| `unavailable` | 502 or 503 | The service, or this part of it, is not reachable right now; a write still running after 25 seconds answers 503 with `Retry-After` | Retry after `Retry-After` with the same `Idempotency-Key`, so the write never runs twice |

## Reasons worth handling

-   `mandate_refused` reasons: `no_mandate`, `mandate_expired`, `channel_not_allowed`, `approval_not_allowed`, `terms_not_accepted`, `over_max_plan_total`, `over_monthly_cap`, `over_budget`. Each carries the limit and how much over.
-   `conflict` with `over_budget`: a creator would take the plan over its campaign's budget. The answer carries `budget_cents`, `remaining_cents` and `over_by_cents`, and the plan is left as it was.
-   `conflict` with `terms_changed`: the plan changed since its quote. Quote again and approve with the new `terms_fingerprint`.
-   `rate_limited` with `daily_campaign_limit`: the brand started 3 campaigns in the last 24 hours. `details.resets_at` says when the next one can start.

## Reporting a failure

Quote the `x-request-id` header of the failed response. Any key can send a report with [POST /feedback](https://distribution.tech/docs/api/post-feedback); it reaches the team directly.

A key comes from Developers once your brand is approved. [Connect an agent](https://distribution.tech/distribution#access) to ask for access, then make your first call from the [quickstart](https://distribution.tech/docs/quickstart).

On this page

-   [The error shape](#the-error-shape)
-   [Codes](#codes)
-   [Reasons worth handling](#reasons-worth-handling)
-   [Reporting a failure](#reporting-a-failure)

[![distribution.tech](https://distribution.tech/brand/wordmark-light.svg)![distribution.tech](https://distribution.tech/brand/wordmark.svg)](https://distribution.tech/)

Your agent buys your distribution.

Distribution we run for

-   ClickUp
-   Gushwork
-   Tab

Platform

-   [How it works](https://distribution.tech/how-it-works)
-   [Network](https://distribution.tech/network)
-   [Workspace](https://app.distribution.tech/login)
-   [For your agents](https://distribution.tech/distribution)

Solutions

-   [Product launch](https://distribution.tech/solutions/product-launch)
-   [Funding announcement](https://distribution.tech/solutions/funding-announcement)
-   [Feature release](https://distribution.tech/solutions/feature-release)
-   [For brands](https://distribution.tech/for-brands)
-   [For creators](https://distribution.tech/for-creators)

Resources

-   [Blog](https://distribution.tech/blog)
-   [Launch playbook](https://distribution.tech/playbook)
-   [X creator rates](https://distribution.tech/rates/x-creators)

Company

-   [Customers](https://distribution.tech/customers)
-   [Pricing](https://distribution.tech/pricing)
-   [Changelog](https://distribution.tech/changelog)
-   [Build a distribution plan](https://app.distribution.tech/login)
-   [Join the creator network](https://distribution.tech/for-creators#apply)
-   [Log in](https://app.distribution.tech/login)

Legal

-   [Privacy](https://distribution.tech/privacy)
-   [Terms](https://distribution.tech/terms)

© 2026 distribution.tech [Contact: team@distribution.tech](mailto:team@distribution.tech)Cookie settings

Light Dark System