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

# Errors

> HTTP status codes and error handling for the Upsun REST API.

The Upsun API uses standard HTTP status codes to indicate the success or failure of a request.

## Status codes

| Code  | Status       | Description                                                              |
| ----- | ------------ | ------------------------------------------------------------------------ |
| `200` | OK           | Request succeeded. Response body contains the requested resource.        |
| `201` | Created      | Resource created successfully. Response body contains the new resource.  |
| `204` | No Content   | Request succeeded with no response body (typically for deletions).       |
| `400` | Bad Request  | Invalid request parameters or body. Check the error message for details. |
| `401` | Unauthorized | Missing or expired access token. Re-authenticate and retry.              |
| `403` | Forbidden    | Valid token but insufficient permissions for the requested action.       |
| `404` | Not Found    | The requested resource does not exist.                                   |
| `409` | Conflict     | Resource already exists or a state conflict prevents the action.         |

## HAL response structure

Successful responses use the [HAL](https://stateless.group/hal_specification.html) (Hypertext Application Language) format. Most responses include:

### `_links`

Most GET endpoints return a `_links` object defining available actions on the resource. The `self` key contains a fully qualified URL and an OpenAPI schema reference. Additional keys use fragment identifiers (e.g., `#edit`, `#delete`) to describe available operations:

```json theme={null}
{
  "_links": {
    "self": {
      "href": "/api/projects/abcdefghij1234567890",
      "meta": { ... }
    },
    "#delete": {
      "href": "/api/projects/abcdefghij1234567890",
      "meta": {
        "delete": {
          "responses": { ... },
          "parameters": []
        }
      }
    }
  }
}
```

### `_embedded`

Requests to endpoints which create or modify objects, such as POST, PATCH, or DELETE requests, include an `_embedded` key in their response. It contains the created or modified object, identical to what would be returned by a subsequent GET request for that resource.