Error Handling

Parsewise API uses standard HTTP status codes to indicate request success or failure. All errors are returned in a unified JSON format.

Error Format

All errors are returned in JSON format with field detail:

{
  "detail": "Error description in English"
}

HTTP Status Codes

Code	Name	Description
`200`	OK	Request successful
`201`	Created	Resource successfully created
`204`	No Content	Successful deletion (no response body)
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Missing or invalid token
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error

Error Examples

400 Bad Request

Invalid request parameters:

{
  "detail": "message: field required"
}

401 Unauthorized

Authentication issues:

{
  "detail": "Invalid authorization header format. Use: Bearer <token>"
}

{
  "detail": "Invalid API token"
}

403 Forbidden

Insufficient permissions:

{
  "detail": "This endpoint requires EDITOR role or higher"
}

404 Not Found

Resource not found:

{
  "detail": "Product not found"
}

{
  "detail": "Chat not found"
}

429 Too Many Requests

Rate limit exceeded:

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

Rate Limits

Request Type	Limit
Standard requests	100 per minute
SSE connections	10 concurrent
Bulk operations	10 per minute

When the limit is exceeded, you'll get a 429 Too Many Requests.

We recommend implementing exponential backoff when receiving a 429 error.

Error Handling in Code

import requests

def make_api_request(endpoint, method="GET", data=None):
    headers = {"Authorization": "Bearer pw_your_token"}
    url = f"https://api.parsewise.ru/v1{endpoint}"
    
    try:
        response = requests.request(method, url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Authentication error. Check your token.")
        elif e.response.status_code == 403:
            print("Insufficient permissions. Use Editor token.")
        elif e.response.status_code == 404:
            print("Resource not found.")
        elif e.response.status_code == 429:
            print("Too many requests. Please wait.")
        else:
            print(f"Error: {e.response.json().get('detail', 'Unknown error')}")
        return None

Retry with Exponential Backoff

For 429 and 5xx errors, we recommend retrying requests with increasing delay:

import time
import random

def request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 200:
            return response.json()
        
        if response.status_code in [429, 500, 502, 503, 504]:
            delay = (2 ** attempt) + random.uniform(0, 1)
            print(f"Retry {attempt + 1}/{max_retries} in {delay:.1f}s")
            time.sleep(delay)
        else:
            response.raise_for_status()
    
    raise Exception("Max retries exceeded")