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

# API error codes and responses

> Borga uses standard HTTP status codes and returns JSON error objects with a type, message, optional code, and the param that caused the error.

Borga uses conventional HTTP status codes to signal whether a request succeeded or failed. When a request fails, the response body is a JSON object with an `error` field containing details about what went wrong.

## Error response format

Every error response has the following shape:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'amount' field must be a positive integer.",
    "code": "invalid_amount",
    "param": "amount"
  }
}
```

| Field           | Type   | Description                                                           |
| --------------- | ------ | --------------------------------------------------------------------- |
| `error.type`    | string | Category of the error. See [error types](#error-types) below.         |
| `error.message` | string | Human-readable description of what went wrong.                        |
| `error.code`    | string | Optional machine-readable error code for programmatic handling.       |
| `error.param`   | string | Optional. The request parameter that caused the error, if applicable. |

<Tip>
  During development, log the full `error` object on every failed request. The `message` and `param` fields often reveal exactly what to fix without needing to consult the docs.
</Tip>

## HTTP status codes

| Status                      | Meaning                                                                           |
| --------------------------- | --------------------------------------------------------------------------------- |
| `200 OK`                    | Request succeeded.                                                                |
| `201 Created`               | Resource was created successfully.                                                |
| `400 Bad Request`           | The request has invalid parameters. Check `error.param` to identify the field.    |
| `401 Unauthorized`          | The `Authorization` header is missing, malformed, or contains an invalid API key. |
| `403 Forbidden`             | The API key is valid but does not have permission to perform this action.         |
| `404 Not Found`             | The requested resource does not exist.                                            |
| `409 Conflict`              | An `Idempotency-Key` was reused with different request parameters.                |
| `422 Unprocessable Entity`  | The request body failed validation. Check `error.param` for the offending field.  |
| `429 Too Many Requests`     | The rate limit has been exceeded. Back off and retry.                             |
| `500 Internal Server Error` | Something went wrong on Borga's side.                                             |

<Note>
  `5xx` errors are safe to retry. Use exponential backoff — for example, wait 1 s, then 2 s, then 4 s — to avoid amplifying load on a degraded service.
</Note>

## Error types

| Type                    | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| `authentication_error`  | The API key is missing, invalid, or has been revoked.                         |
| `invalid_request_error` | The request is malformed or contains invalid parameter values.                |
| `not_found_error`       | The referenced resource does not exist or is not accessible with this key.    |
| `permission_error`      | The API key does not have the required permissions for this operation.        |
| `rate_limit_error`      | Too many requests have been made in a short period.                           |
| `api_error`             | An unexpected error occurred on Borga's side. Retry with exponential backoff. |