Errors & Status

Understanding error responses and execution statuses helps you build robust integrations with the AutoRetouch API.

HTTP Status Codes

Success Codes

Code	Meaning	Description
200 OK	Success	Request completed successfully
201 Created	Created	Resource created (e.g., execution, upload)

Client Error Codes

Code	Meaning	Description
400 Bad Request	Invalid request	Malformed request body or parameters
401 Unauthorized	Authentication required	Missing or invalid access token
403 Forbidden	Access denied	Valid token but insufficient permissions
404 Not Found	Resource not found	Workflow, execution, or image doesn’t exist
422 Unprocessable Entity	Invalid content	Image cannot be processed (format, size, etc.)

Server Error Codes

Code	Meaning	Description
500 Internal Server Error	Server error	Unexpected error on our side
503 Service Unavailable	Temporarily unavailable	Service is temporarily down

Error Response Format

Most error responses follow this JSON structure:

{
  "timestamp": "2020-09-16T21:09:15.863+00:00",
  "status": 404,
  "error": "Not Found",
  "message": "Workflow execution not found",
  "path": "/v1/workflow/execution/invalid-id"
}

Field	Description
timestamp	When the error occurred (ISO 8601)
status	HTTP status code
error	Error type
message	Human-readable description
path	Request path that caused the error

Authentication Errors

OAuth errors use a different format:

{
  "error": "invalid_grant",
  "error_description": "Invalid or expired device code."
}

Error	Description
invalid_grant	Device code expired, invalid, or refresh token revoked
authorization_pending	User hasn’t confirmed device yet (keep polling)
slow_down	Polling too frequently (increase interval)

---

Execution Statuses

Workflow executions go through several states:

Status	Description	Action
CREATED	Execution queued, waiting to start	Wait for processing
ACTIVE	Currently processing	Wait for completion
COMPLETED	Successfully finished	Download result
IN_QA	Awaiting quality assurance review	Wait for QA approval
PAYMENT_REQUIRED	Insufficient credits	Add credits, then retry
FAILED	Processing failed	Retry or investigate

Status Flow

CREATED → ACTIVE → COMPLETED
                 → IN_QA → COMPLETED
                 → PAYMENT_REQUIRED
                 → FAILED

Handling Each Status

COMPLETED

The execution finished successfully. The response includes:

• resultPath: Path to download the result image
• resultContentHash: Hash of the result image
• chargedCredits: Credits consumed

IN_QA

The execution has finished processing but is awaiting quality assurance review. This happens when QA is enabled for the workflow or batch.

Resolution:

• Wait for QA approval in the AutoRetouch web app
• Use webhooks to get notified when the status changes

PAYMENT_REQUIRED

The organization’s credit balance was insufficient when the execution was created or processed.

Resolution:

1. Add credits to the organization
2. Call the retry endpoint

FAILED

The execution encountered an error during processing. This could be due to:

• Invalid input image
• Processing component failure
• System error

Resolution:

1. Check the input image is valid
2. Retry the execution (no additional cost)
3. If persistent, contact support

---

API Health Check

Check if the API is available:

GET https://api.autoretouch.com/health

Returns 200 OK with empty body if healthy.

Check a specific API version:

GET https://api.autoretouch.com/v1/health

Returns 200 OK if the v1 API is available and supported.

---

Rate Limiting

The API implements rate limiting to ensure fair usage. Rate limit headers are included in responses:

Header	Description
X-RateLimit-Limit	Maximum requests allowed
X-RateLimit-Remaining	Requests remaining in window
X-RateLimit-Reset	Unix timestamp when limit resets

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Wait until the reset time before retrying.

---

Best Practices

Retry Strategy

Implement exponential backoff for transient errors:

import time
import requests

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response

        if response.status_code in [429, 500, 503]:
            wait_time = (2 ** attempt) + 1  # 1s, 3s, 5s
            time.sleep(wait_time)
            continue

        # Non-retryable error
        response.raise_for_status()

    raise Exception("Max retries exceeded")

Error Handling Checklist

1. Always check HTTP status codes before parsing response body
2. Handle 401 errors by refreshing the access token
3. Log error responses including the full response body for debugging
4. Implement retries for 429, 500, and 503 errors
5. Monitor execution statuses and handle FAILED/PAYMENT_REQUIRED appropriately