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

# Errors

> Error format, HTTP status codes, and troubleshooting

All Partner API errors return a consistent JSON format with an HTTP status code indicating the error category.

## Error format

```json theme={null}
{
  "success": false,
  "error": "Human-readable error message"
}
```

## HTTP status codes

| Status | Meaning | Common causes |
| - | - | - |
| **400** | Bad request | Missing required fields, invalid field values, malformed JSON |
| **401** | Unauthorized | Missing `x-contro-api-key` header, invalid or expired API key |
| **404** | Not found | Resource does not exist or belongs to a different partner |
| **429** | Rate limited | Exceeded 1,000 requests per minute |
| **500** | Internal server error | Unexpected server issue - retry with backoff |

## Troubleshooting

### 400 Bad request

The request body or query parameters are invalid.

**Check:**

* Required fields are present (`externalUserId`, `firstName`, `lastName`, `email` for cardholders)
* Field types match the schema (e.g., `limit` is a number, not a string)
* Email addresses are valid format
* The request body is valid JSON with `Content-Type: application/json`

### 401 Unauthorized

The API key is missing or invalid.

**Check:**

* The `x-contro-api-key` header is present: `x-contro-api-key: sk_test_...`
* The key prefix matches your environment (`sk_test_*` for sandbox, `sk_live_*` for production)
* The key has not been revoked or rotated

### 404 Not found

The requested resource does not exist.

**Check:**

* The resource ID is correct
* The resource belongs to your partner account (you cannot access other partners' resources)
* The resource has not been deleted

### 429 Rate limited

You've exceeded the rate limit of 1,000 requests per minute.

**Handle:**

* Read the `Retry-After` header to determine when to retry
* Implement exponential backoff in your client
* Consider batching operations or caching responses

### 500 Internal server error

An unexpected error occurred on the server.

**Handle:**

* Retry the request after a short delay (1–5 seconds)
* Use exponential backoff for repeated failures
* If the error persists, contact support with the request details

## Best practices

* **Check the error message** - it describes what went wrong in human-readable terms
* **Use idempotency keys** - when issuing cards, pass `idempotencyKey` to safely retry failed requests
* **Implement retry logic** - for 429 and 500 errors, retry with exponential backoff
* **Log error responses** - capture the full response for debugging