API error codes and responses - Borga

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:

{
  "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.