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

# Errors

> JSON error shape and the HTTP status codes returned across every endpoint.

## Error body shape

All errors return a JSON body of the form:

```json theme={null}
{
  "code": "<error-code>",
  "message": "<human-readable description>",
  "extra": "<context-specific detail, e.g. the offending userId>"
}
```

The `extra` field carries the most-useful piece of context for debugging — typically a UUID or field path that explains why the request was rejected.

## Status codes

| HTTP                                  | Code           | Cause                                                                                                                                                                                                      |
| ------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`                     | varies         | Malformed query parameter (for example, `limit` greater than `1000`, or a non-numeric `since`).                                                                                                            |
| `401 Unauthorized`                    | `unauthorized` | Missing or invalid session cookie. Re-authenticate via the [login flow](/events-auctions/authentication).                                                                                                  |
| `403 Forbidden`                       | `forbidden`    | The caller is not authorized. For Custom Data Export paths this is usually the dedicated service-user check failing. For all paths, it can also mean the user does not have access to the requested event. |
| `404 Not Found`                       | `not_found`    | The supplied `eventId` does not resolve to an event the caller can see — either no event with that id exists, or the event is in a region/account the caller cannot access.                                |
| `429 Too Many Requests`               | —              | Rate-limit zone exceeded. Back off and retry. See [Rate limiting](/events-auctions/rate-limiting).                                                                                                         |
| `503 Service Temporarily Unavailable` | —              | Sustained traffic above rate-limit zone capacity, or an upstream component is overloaded. Retry with exponential backoff.                                                                                  |
| `5xx` (other)                         | varies         | Transient server error. Retry with exponential backoff.                                                                                                                                                    |

## Example: 403 on a Custom Data Export path

```json theme={null}
{
  "code": "forbidden",
  "message": "Access forbidden: not a <namespace> client",
  "extra": "11111111-2222-3333-4444-555555555555"
}
```

This is the response you'll get if you call a Custom Data Export endpoint with a session that isn't the configured service user for your integration. The `extra` field contains your authenticated user's UUID — useful when contacting support. The exact `message` text varies per integration namespace; the `code` and `extra` shape are consistent.

<Note>
  If you see this error and believe your account should have access, contact [support@givergy.com](mailto:support@givergy.com) with the UUID from the `extra` field. The team can verify your account's provisioning state.
</Note>

## Retry guidance

| Status        | Retry?               | How                                                                                                                                      |
| ------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400`         | No — fix the request | Inspect `extra`, correct the offending parameter, then resend.                                                                           |
| `401`         | After re-auth        | Re-run the login flow to get a fresh session cookie.                                                                                     |
| `403`         | No — escalate        | The caller isn't authorized for this resource. Contact [support@givergy.com](mailto:support@givergy.com) if you expected to have access. |
| `404`         | Sometimes            | If the `eventId` is correct, the event may not yet be visible to your user. Check with the event owner.                                  |
| `429` / `503` | Yes — with backoff   | Exponential backoff starting at a few seconds. See [Rate limiting](/events-auctions/rate-limiting).                                      |
| `5xx`         | Yes — with backoff   | Treat as transient.                                                                                                                      |