# Error reference

Error envelopes and HTTP status codes for the Rezzy Public API

Source: https://docs.rezzy.dev/errors
Documentation index: https://docs.rezzy.dev/llms.txt



REST errors use the same envelope as successful responses, with `success: false` and an appropriate HTTP status code. MCP tool errors use a different format; see [MCP](https://docs.rezzy.dev/mcp#errors).

## Standard error envelope

```json
{
  "success": false,
  "message": "Human-readable error message",
  "data": {
    "error_code": "BAD_REQUEST",
    "details": {}
  }
}
```

`error_code` identifies the error category. `details` contains additional information when available. Check the HTTP status and error code rather than matching message text.

## Validation errors

Missing required fields, incorrect types, and titles longer than 255 characters return **400 Bad Request**, with `error_code: "BAD_REQUEST"`. Multiple validation messages are joined with `; `.

```json
{
  "success": false,
  "message": "title should not be empty",
  "data": {
    "error_code": "BAD_REQUEST",
    "details": {}
  }
}
```

Business validation also returns **400**, with `error_code: "VALIDATION_ERROR"`: for example, an incomplete profile import, an invalid or unreachable company URL, or an invalid cover letter date.

Unknown request body fields are stripped. Duplicate document titles are resolved by adding a suffix such as `_1`; they do not produce a conflict error.

## HTTP status codes

| Code | Error code                                  | Meaning                                                         |
| ---- | ------------------------------------------- | --------------------------------------------------------------- |
| 200  | —                                           | Status retrieved                                                |
| 202  | —                                           | Generation job accepted                                         |
| 400  | `BAD_REQUEST` or `VALIDATION_ERROR`         | Invalid request, malformed UUID, or business validation failure |
| 401  | `UNAUTHORIZED`                              | Missing or invalid API key                                      |
| 403  | `FORBIDDEN`                                 | Insufficient generation credits                                 |
| 404  | `NOT_FOUND`                                 | Document does not exist or does not belong to your account      |
| 429  | `RATE_LIMIT_EXCEEDED`                       | Request limit exceeded                                          |
| 500  | `INTERNAL_ERROR` or `INTERNAL_SERVER_ERROR` | Server error                                                    |
| 503  | `SERVICE_UNAVAILABLE`                       | Required service unavailable                                    |

## Rate limit errors

```json
{
  "success": false,
  "message": "Too many requests. Please try again later.",
  "data": {
    "error_code": "RATE_LIMIT_EXCEEDED",
    "details": { "retry_after": 45 }
  }
}
```

Wait for the `Retry-After` duration in seconds before retrying. See [Rate limiting](https://docs.rezzy.dev/rate-limiting) for limits and headers.

Creation is not idempotent. If a connection fails after sending a create request, the job may already have been queued and charged. Do not automatically repeat creation after an ambiguous failure; check the dashboard first. Status reads can be retried with backoff.