Error Handling

The Storeep API uses standard HTTP status codes and returns structured JSON error responses.

Error Response Format

All error responses follow this structure:

JSON

{
    "status": "error",
    "errors": [
        "description of what went wrong"
    ]
}

The errors field is always an array. For authentication errors, it contains string messages. For validation errors (422), it is an object with field names as keys.

422 Validation Error

{
    "status": "error",
    "errors": {
        "limit": "limit must be an integer",
        "sort_order": "sort order must be ASC or DESC"
    }
}

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded. Response contains the requested data.
401	Unauthorized	Authentication failed. Missing, invalid, or expired access token.
403	Forbidden	Token is valid but lacks the required permission for this endpoint.
422	Unprocessable Entity	Request parameters are invalid. Check the `errors` object for field-specific messages.
429	Too Many Requests	Rate limit exceeded. Wait and retry. See Rate Limits.
500	Internal Server Error	Something went wrong on our end. Retry later or contact support.

Common Errors

Authentication Errors (401)

Error Message	Cause	Fix
`authorization header is missing`	No `Authorization` header in request.	Add `Authorization: Bearer YOUR_TOKEN` header.
`access token format is invalid`	Token is not a valid UUID.	Check the token format matches `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
`access token is invalid`	Token does not exist or was deleted.	Create a new token in Settings → Access tokens.
`access token has expired`	Token's expiration date has passed.	Create a new token with a future expiration date or set to "Never".

Permission Errors (403)

Error Message	Cause	Fix
`insufficient permissions, requires: products:read`	Token lacks `products:read` permission.	Edit the token in Settings → Access tokens to add the required permission.
`insufficient permissions, requires: orders:read`	Token lacks `orders:read` permission.	Edit the token in Settings → Access tokens to add the required permission.

Validation Errors (422)

Field	Error Message
`search`	`search must be a string` or `search term too long (max 255 characters)`
`market`	`market must be a string or array of strings`, `market cannot exceed 20 values`, or `each market must be a valid country code`
`limit`	`limit must be an integer`, `limit must be at least 1`, or `limit cannot exceed 50`
`page`	`page must be an integer` or `page must be at least 1`
`sort_field`	`sort field must be created_at or updated_at`
`sort_order`	`sort order must be ASC or DESC`

Best Practices

Always check the status code before parsing the response body.
Handle 429 responses by implementing exponential backoff with a maximum retry count.
Log error responses for debugging, the errors field provides specific details.
Don't retry 401/403 errors, these require token changes, not retries.