> ## Documentation Index
> Fetch the complete documentation index at: https://developers.tapfiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error formats of the REST API and the messages integrations run into most often.

<Tip>
  Send `Accept: application/json` with every request. Without it, some errors (for example `401` without a key, or `404` for an unknown path) come back as an HTML page instead of JSON.
</Tip>

## Formats

Errors come in two shapes, depending on where the request stopped.

**Business and validation errors** — `400`, `403`, `404` and `409` raised by an endpoint — return a list of errors:

```json theme={null}
{
  "errors": [
    { "message": "Duplicate conversion. There is already a conversion for External id 'ORD123'" }
  ]
}
```

Validation errors also name the field: `property_path` and `message_raw`. `409` errors carry a machine-readable `code`.

**Request-level errors** — a missing key, no access, an unknown path or a server error — return a single object:

```json theme={null}
{ "message": "Not Found", "code": 404, "traceId": "7ae8e92b77572da0…" }
```

If something goes wrong on our side, send the `traceId` to support: it lets us find your request.

A wrong API key always returns `{"message": "Authentication Failed.", "code": 401}`.

## Status codes

| Status | Meaning |
| - | - |
| `400` | The request is invalid. The message says what to change. |
| `401` | The API key is missing or wrong. |
| `403` | Your user has no API access, lacks the permission for this action, or the feature isn't on your plan. |
| `404` | The path or the object doesn't exist, or belongs to another account. |
| `405` | The endpoint doesn't support this HTTP method. |
| `409` | The object is in a state that doesn't allow the change, see [conflicts](#conflicts). |
| `429` | Too many requests, see [rate limits](/api-reference/introduction#rate-limits). |
| `5xx` | Something went wrong on our side. Retry later with a delay and send the `traceId` to support if it persists. |

## Common errors when tracking

These come from **Create a conversion**, **Create a customer** and the [postbacks](/tracking/server-to-server). Messages are quoted exactly as the API returns them, so you can match them in your logs.

| Message | What happened | What to do |
| - | - | - |
| `Missing mandatory parameter(s)` | No way to attribute the conversion was sent. | Send `referral_code`, `coupon`, `click_id` or `asset_id` with `source_id`. |
| `Parameter '…' takes precedence for tracking, but no value was passed` | The highest-priority field was sent empty, for example `"coupon": ""`. | Leave out fields you don't have instead of sending them empty. |
| `Unknown referral code`, `Unknown coupon code`, `Invalid click id` | The value doesn't match an affiliate in your account. | Check the value you pass on. |
| `Cookie expired` | The affiliate's click is older than the program's cookie time. | Expected for late conversions. To track anyway, add `?override_max_cookie_time=true`. |
| `Duplicate conversion. There is already a conversion for External id '…'` | A conversion with this `external_id` already exists. | Treat it as recorded. Look it up with `GET /conversions/?external_id=…` if needed. |
| `To many concurrent attempts to create conversion with id '…'` | A retry arrived within 10 seconds of a failed attempt with the same ID. | Wait more than 10 seconds before retrying. |
| `Missing tracking parameter value and no customer found for customer id: …` | Only `customer_id` was sent, and no such customer exists. | Create the customer first, or send a tracking parameter too. |
| `Affiliate is not approved for this program`, `Affiliate is deleted` | The affiliate can't earn in this program. | Approve the affiliate in the program. |
| `Program is archived` | The program no longer accepts conversions. | Track to an active program. |
| `Duplicate customer. There is already a customer for Customer id '…'` | The customer exists already. | Use the existing customer. |
| `Invalid status '…'. Valid are 'new', 'trial', 'lead'` | Unknown initial customer status. | Use one of the listed values. |
| `Request body was not valid JSON` | The body isn't a JSON object. | Send a JSON object with `Content-Type: application/json`. |
| `Advertiser account locked` | Your account is locked. | Contact support. |

When listing, `Invalid date` means `date_from` or `date_to` isn't a valid `YYYY-MM-DD` date.

## Conflicts

`409` responses explain why the object can't change and include a `code`:

| `code` | Meaning |
| - | - |
| `commission_approved` | The commission is approved and your account uses Tapfiliate Pay, so it can't be disapproved or approved again. |
| `commission_unfunded` | The commission can't be approved: your Tapfiliate Pay balance doesn't cover what is already owed. |
| `program_archived` | The program is archived and can't be modified. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.