> For the complete documentation index, see [llms.txt](https://docs.floral.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.floral.fun/developer-resources/errors.md).

# Errors

`/v1` errors use one shape:

```json
{ "error": { "code": "target_not_found", "message": "That target doesn't exist or isn't public." } }
```

| Status | Code                                                                                                                                         | Meaning                                                                                       |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 400    | `invalid_id`, `invalid_limit`, `invalid_cursor`                                                                                              | A parameter is malformed                                                                      |
| 400    | `invalid_request`                                                                                                                            | The body isn't valid JSON                                                                     |
| 413    | `invalid_request`                                                                                                                            | The body is larger than 2 MB                                                                  |
| 400    | `invalid_action`, `invalid_target`, `invalid_user_id`, `user_id_required`, `invalid_campaign_window`, `invalid_campaign_id`, `invalid_rules` | The verification request is malformed                                                         |
| 401    | `invalid_token`                                                                                                                              | Missing, expired or revoked token. The partner may also be suspended, or the user deactivated |
| 403    | `insufficient_scope`                                                                                                                         | The token lacks the scope                                                                     |
| 403    | `user_token_required`                                                                                                                        | This endpoint needs a user token                                                              |
| 403    | `user_mismatch`                                                                                                                              | `user_id` isn't the token's user                                                              |
| 403    | `user_not_linked`                                                                                                                            | The user hasn't granted your platform access                                                  |
| 404    | `not_found`, `target_not_found`                                                                                                              | Doesn't exist, isn't public, or there's no such endpoint                                      |
| 429    | `rate_limited`                                                                                                                               | See [Rate limits](/developer-resources/rate-limits.md)                                        |
| 500    | `server_error`                                                                                                                               | Retry with backoff                                                                            |

[Verification errors](/api-reference/verification.md#errors) lists when each verification code applies.

## OAuth errors

`/oauth` endpoints use the standard OAuth shape:

```json
{ "error": "invalid_grant", "error_description": "The grant is invalid, expired or revoked." }
```

| Status | Error                    | What to do                                                                                                                                   |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`        | The body isn't valid JSON                                                                                                                    |
| 413    | `invalid_request`        | The body is too large                                                                                                                        |
| 400    | `invalid_grant`          | The code or refresh token is invalid, expired, already used, or the user disconnected. Send the user through Floral Connect again            |
| 400    | `invalid_scope`          | A refresh asked for more than the original scopes                                                                                            |
| 400    | `unsupported_grant_type` | Check `grant_type`                                                                                                                           |
| 400    | `unauthorized_client`    | Public clients can't use `client_credentials`                                                                                                |
| 401    | `invalid_client`         | Check `client_id` and `client_secret`. The application may also be disabled, suspended or deleted, or a public client may have sent a secret |
| 429    | `slow_down`              | Wait for `Retry-After`                                                                                                                       |
| 500    | `server_error`           | Retry with backoff                                                                                                                           |

`GET /oauth/authorize` returns these as `400` JSON and doesn't redirect:

| Error                  | Meaning                                                     |
| ---------------------- | ----------------------------------------------------------- |
| `invalid_client`       | The `client_id` is unknown, or the application isn't active |
| `invalid_redirect_uri` | `redirect_uri` doesn't exactly match a registered URL       |

These can come back on your `redirect_uri` during authorization:

| Error                       | Meaning                                           |
| --------------------------- | ------------------------------------------------- |
| `access_denied`             | The user cancelled                                |
| `invalid_scope`             | A scope is unknown or not allowed for your client |
| `invalid_request`           | A PKCE parameter is missing or malformed          |
| `unsupported_response_type` | `response_type` must be `code`                    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.floral.fun/developer-resources/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.