Errors
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
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
404for access denial - Metrics endpoint returns
403for unauthorized users - Collection and publication endpoints return
400for 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 — resolve 401 authentication errors
- Permissions and access control — understand 403 and 404 behavior
- Token lifecycle & session management — handle token expiry
- Metrics and analytics — 403 on restricted metrics endpoints
- Collections — 400 for missing publication URL
- Support — get help with persistent errors
