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

# Errors

> Handling of REST API error responses

# Error Responses

The API uses [RFC 9457 Problem Details for HTTP APIs](https://datatracker.ietf.org/doc/html/rfc9457) for error responses, with content type `application/problem+json`. All error responses follow a consistent structure designed to provide clear, actionable information about what went wrong.

## Error Structure

All error responses use the following structure:

```json theme={null}
{
  "title": "Error Title",
  "status": 400,
  "detail": "Human-readable explanation of the problem",
  "errors": [
    {
      "location": "body.field_name",
      "message": "Specific error message",
      "value": "problematic_value"
    }
  ]
}
```

### Fields

* **`title`**: A short, human-readable summary of the problem type
* **`status`**: The HTTP status code
* **`detail`**: A human-readable explanation specific to this occurrence of the problem
* **`errors`** *(optional)*: An array of detailed error information, including:
  * **`location`**: Where the error occurred (e.g., `body.items[3].tags` or `path.user-id`)
  * **`message`**: Specific error message text
  * **`value`**: The problematic value that caused the error

## Common Error Codes

### 400 Bad Request

Returned when the request cannot be processed due to malformed syntax, invalid JSON, or other client errors.

```json theme={null}
{
  "title": "Bad Request",
  "status": 400,
  "detail": "validation failed",
  "errors": [
    {
      "message": "invalid character ',' looking for beginning of value",
      "location": "body",
      "value": "{\n  \"field_name\":,\n  \"another_field\": true\n}"
    }
  ]
}
```

### 401 Unauthorized

Returned when authentication is required but has failed or not been provided. The API supports multiple authentication methods, and different failure modes will return specific error messages.

```json theme={null}
{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unauthorized: invalid authorization header",
  "errors": [
    {
      "message": "invalid authorization header",
      "location": "authorization"
    }
  ]
}
```

#### Common 401 Reasons

* **`malformed authorization header`**: The `Authorization` header doesn't follow the expected `Bearer <token>` format
* **`invalid authorization header`**: The provided token is invalid, expired, or cannot be parsed
* **`expired jwt`**: The JWT token has passed its expiration time and is no longer valid
* **`application not found`**: The application referenced in the token doesn't exist
* **`application not active`**: The application exists but is not in an active state

### 403 Forbidden

Returned when the authenticated user or application lacks permission to access the requested resource or perform the requested action.

```json theme={null}
{
  "title": "Forbidden",
  "status": 403,
  "detail": "Nutrition Records are not enabled for this application"
}
```

### 413 Request Entity Too Large

Returned when the request payload exceeds the maximum allowed size. The API limits request payloads to **10 MB**.

```json theme={null}
{
  "title": "Request Entity Too Large",
  "status": 413,
  "detail": "request body is too large limit=10485760 bytes"
}
```

### 422 Unprocessable Entity

Returned when the request is syntactically correct but contains validation errors. This includes schema validation failures, business rule violations, and data consistency issues.

```json theme={null}
{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "message": "expected value to be one of \"option1, option2, option3\"",
      "location": "body.field_name",
      "value": "invalid_option"
    },
    {
      "message": "field is required",
      "location": "body.required_field"
    }
  ]
}
```

### 500 Internal Server Error

Returned when an unexpected server-side error occurs. In production environments, sensitive error details are encrypted and replaced with a reference code that can be shared with support.

```json theme={null}
{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Internal error at 1754296226: Share the following reference code with support: o8XIyE2aubQXVvgbiK6jDRjmJAdZRl9na1PBOm7tq_5Vi0o53ZHMzBc9JxUQfuNHcSLt7jEXnrMIrxRjrSFQBC9-BfwEVPEc5JqNueh9egsodrxmCsnzoD6EaKJoH2QbEup_pBuVQZNQIRzfssluj3jbuLmdCNnBJ86ygiM_V0pvNnPBsrNWXZj1uQ"
}
```

**Note**: When you encounter a 500 error, please share the reference code with our support team. This encrypted reference contains the technical details needed to diagnose and resolve the issue while protecting sensitive system information.

## Error Handling Best Practices

1. **Check the `status` field** to determine the error category
2. **Read the `detail` field** for a human-readable explanation
3. **Process the `errors` array** for specific validation failures
4. **Use the `location` field** to identify which input fields need correction
5. **For 400 errors**, review the `errors` array to identify the specific field that caused the error
6. **For 401 errors**, check your authentication credentials and token validity
7. **For 413 errors**, reduce your payload size to under 10 MB
8. **For 422 errors**, review each item in the `errors` array to fix validation issues
9. **For 500 errors**, save the reference code and contact support

## Exhaustive Error Reporting

The API strives to return exhaustive errors whenever possible to prevent frustration from repeated failed requests. When multiple validation errors occur, all detected issues are included in a single response rather than failing on the first error encountered.