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

# Errors

> HTTP status codes and error body shape for the CurbWaste partner API, including auth, scopes, not-found, and rate limits.

Partner API `/v1` errors return JSON with a machine-readable `code`, a human-readable `message`, and an `internalRequestId`. Some errors also include `extraData`.

```json theme={null}
{
  "code": "BAD_REQUEST",
  "message": "At least one updatable field is required",
  "internalRequestId": "…"
}
```

## Status codes

| Status | `code` | When | What to do |
| - | - | - | - |
| `400` | `BAD_REQUEST` | Validation failed (empty update body, unknown expand, invalid field, …) | Fix the request body or query |
| `401` | `UNAUTHORIZED` | Missing or invalid `Authorization: Bearer cw_live_…` | Create or rotate a key in the [Developer Platform](https://platform.curbwaste.com) |
| `403` | `NO_PERMISSIONS` | Key is valid but missing the required scope | Add the needed scope (for example `customers:read`, `catalog:write`, `locations:read`) in the Developer Platform |
| `404` | `NOT_FOUND` | Resource id not found **for this company** | Check the id; cross-tenant ids look like 404 |
| `429` | `REQUEST_LIMIT_EXCEEDED` | Partner API rate limit exceeded | Back off; honor `Retry-After` and `extraData.retryAfter` (seconds). See [Usage](/api-reference/usage) |
| `5xx` | varies | Unexpected server error | Retry later; contact support if persistent |

<Tip>
  Treat `404` as both “missing” and “not in your company.” Do not use 404 responses to probe other tenants.
</Tip>

<Note>
  If **your** webhook receiver rejects a bad HMAC signature, return `401` from that receiver. That is separate from partner API auth — see [Webhook setup](/guides/webhooks-setup).
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Usage" icon="gauge-high" href="/api-reference/usage">
    Company rate limits for REST and MCP, and how to handle `429`.
  </Card>

  <Card title="Overview" icon="book-open" href="/api-reference/overview">
    Base URL, response wrappers, and pagination conventions.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API keys, Bearer tokens, and scopes.
  </Card>

  <Card title="Webhook setup" icon="webhook" href="/guides/webhooks-setup">
    Verify signatures on inbound deliveries to your URL.
  </Card>
</CardGroup>


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