***

title: Errors
description: How AISquare APIs return errors and how to handle them.
--------------------------------------------------------------------

This guide explains how AISquare APIs return errors and how to handle them.

***

## Overview

AISquare APIs use standard HTTP status codes to indicate success or failure.

Error responses are returned when:

* Authentication fails
* Input is invalid
* Access is restricted
* Resources are not found

***

## Common status codes

| Status | Meaning                               |
| ------ | ------------------------------------- |
| `200`  | Request successful                    |
| `201`  | Resource created successfully         |
| `204`  | Resource deleted successfully         |
| `400`  | Invalid request or missing parameters |
| `401`  | Authentication required or failed     |
| `403`  | Access forbidden                      |
| `404`  | Resource not found or access denied   |
| `500`  | Internal server error                 |

***

## Authentication errors

### 401 Unauthorized

Returned when:

* Authentication is missing
* Token or API key is invalid
* Session has expired

### Handling

* Ensure authentication credentials are included
* Verify token or API key
* Re-authenticate if needed

***

## Permission errors

### 403 Forbidden

Returned when:

* User does not have required role
* Endpoint is restricted (e.g. owner-only metrics)

### Handling

* Verify user role and permissions
* Ensure correct access level

***

## Not found errors

### 404 Not Found

Returned when:

* Resource does not exist
* Publication is invalid
* Access is restricted (for non-public resources)

### Handling

* Verify identifiers (`id`, `url`, `username`)
* Confirm user has access
* Treat as "not accessible" if required

***

## Validation errors

### 400 Bad Request

Returned when:

* Required fields are missing
* Request format is invalid
* Query parameters are incorrect

### Handling

* Validate request body
* Ensure required fields are present
* Check parameter formats

***

## Server errors

### 500 Internal Server Error

Returned when:

* Unexpected failure occurs on the server

### Handling

* Retry request if appropriate
* Log error for debugging
* Contact support if issue persists

***

## Endpoint-specific notes

Some endpoints have specific error behavior:

* **Permission endpoint** may return `404` for access denial
* **Metrics endpoint** returns `403` for unauthorized users
* **Collection and publication endpoints** return `400` for missing URL

***

## Best practices

### Validate inputs before sending requests

Avoid unnecessary `400` errors.

### Handle authentication failures centrally

Implement retry or re-auth logic.

### Do not assume 404 always means missing

It may indicate restricted access.

### Log errors

Capture status codes and responses for debugging.

***

## Related pages

* [Authentication](/docs/getting-started/authentication) — resolve 401 authentication errors
* [Permissions and access control](/docs/data-ux-guides/permissions-and-access-control) — understand 403 and 404 behavior
* [Token lifecycle & session management](/docs/integration-guides/token-lifecycle-session-management) — handle token expiry
* [Metrics and analytics](/docs/insights/metrics-and-analytics) — 403 on restricted metrics endpoints
* [Collections](/docs/product/collections) — 400 for missing publication URL
* [Support](/docs/reference/support) — get help with persistent errors