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.
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.
Every error response has the following shape:
{
"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 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. |
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.
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. |
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.
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. |