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

# Errors

> Every refusal has one shape and a sentence that says what to do. What each code means, and how to answer it.

Every refusal is the same shape, with the status that matches its code:

```json theme={null}
{ "error": { "code": "conflict", "message": "Northwind Dental isn't one of the team's targets. Add it first with POST /v1/targets { \"company\": \"northwind-dental\" }." } }
```

The `message` is a plain sentence a person can act on, and it often names the call to make first. Read it before you try anything else, and tell the person when it's theirs to answer.

| Status | Code | What it means, and what to do |
| - | - | - |
| `400` | `bad_request` | A parameter or a field is wrong, and the message names it. Fix the request; asking again unchanged gets the same answer. |
| `401` | `no_key` | No key, a key that isn’t PodData’s, a revoked one, or a staging key on production. Check `PODDATA_API_KEY`; never paste the key into a chat. |
| `403` | `plan` | The team’s plan doesn’t include this, or a limit a UTC day is used up, and the message says which and when it opens again. Wait, or ask the person. |
| `403` | `forbidden` | This caller may not do this: a key where a person signed in to the workspace is needed, or a role on the team that doesn’t allow it. The message says who can. |
| `404` | `not_found` | Nothing here by that id, or nothing your team may see. It never says whether another team has it. |
| `409` | `conflict` | It clashes with what’s there: a company that isn’t a target yet, a link confirmed for another company, a report saved over since you read it. The message says what to do first. |
| `422` | `unclear` | PodData couldn’t read what was meant, such as a tracker sentence, and the message asks the question to answer. |
| `429` | `slow_down` | More than 120 requests in a minute with this key. Wait the seconds in `Retry-After`, then carry on. |
| `500` | `internal` | Something went wrong at PodData. Ask again after a minute; if it goes on, tell PodData what you asked and when. |

## How to answer one

1. **Read `code` and `message`.** The code says what kind of refusal it is; the message says what to do.
2. **Don't ask again unchanged.** A `400`, `403`, `404` or `409` answers the same until something changes: fix the request, or do what the message says first.
3. **Wait on a `429`.** Wait the seconds `Retry-After` gives, then carry on.
4. **Try a `500` once more** after a minute. If it goes on, stop and say what you asked and when.
5. **Through the MCP server,** a refusal is the tool's answer, marked as an error, with the same sentence.


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