Errors
The Apertur API uses standard HTTP status codes. All error responses include a JSON body with details.
Error format
Every error response follows this structure:
{
"statusCode": 400,
"error": "Bad Request",
"message": "delivery_mode is required"
}| Field | Type | Description |
|---|---|---|
| statusCode | integer | The HTTP status code |
| error | string | Short error name (e.g., "Bad Request") |
| message | string | Human-readable description of the error |
HTTP status codes
400Bad Request
The request body or parameters are invalid.
Common causes
- •Missing required field (e.g., delivery_mode)
- •Invalid field value or type
- •webhook_url missing when delivery_mode is webhook
401Unauthorized
Authentication failed. The API key is missing or invalid.
Common causes
- •No Authorization header
- •Malformed Bearer token
- •API key does not exist or has been deleted
403Forbidden
The API key is valid but does not have permission for this action.
Common causes
- •Session belongs to a different project
- •Account suspended
- •Plan does not allow this feature
404Not Found
The requested resource does not exist.
Common causes
- •Session ID not found
- •Image ID not found
- •Invalid route path
409Conflict
The request conflicts with the current state of the resource.
Common causes
- •Session is already completed — cannot upload more images
- •Image already acknowledged
410Gone
The resource existed but is no longer available.
Common causes
- •Session has expired
- •All images have been acknowledged (long polling complete)
429Too Many Requests
The rate limit for this API key has been exceeded.
Common causes
- •Exceeded per-minute request limit
- •Exceeded monthly session quota for your plan
500Internal Server Error
An unexpected error occurred on our servers.
Common causes
- •Transient infrastructure issue — retry with exponential backoff
- •If persistent, check our status page
Handling errors in code
# Show both headers and body to inspect error responses
curl -v -X POST https://api.apertur.ca/v1/sessions \
-H "Authorization: Bearer aptr_xxxx" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
-d '{"delivery_mode": "webhook", "webhook_url": "https://your-app.com/webhook"}'
# Example error response (400):
# {"statusCode":400,"error":"Bad Request","message":"delivery_mode is required"}