Skip to main content

​
Error Response Format

All Upwell API errors follow a consistent format to help you quickly identify and resolve issues: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": {
      "field": "invoice_id",
      "issue": "Invoice ID must be a valid UUID"
    }
  },
  "status": "error",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
HTTP Status Codes

Status CodeDescriptionCommon Causes
200SuccessRequest completed successfully
201CreatedResource created successfully
400Bad RequestInvalid request parameters or format
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions for the requested operation
404Not FoundRequested resource does not exist
409ConflictResource already exists or conflicting operation
422Unprocessable EntityValid request format but invalid business logic
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error occurred
503Service UnavailableAPI temporarily unavailable

​
Common Error Codes

​
Authentication Errors

HTTP Status: 401 Description: The provided API key is invalid or expired Solution: Verify your API key and regenerate if necessary
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}
HTTP Status: 401 Description: Authorization header is missing from the request Solution: Include your API key in the Authorization header
{
  "error": {
    "code": "MISSING_AUTHORIZATION",
    "message": "Authorization header is required"
  }
}

​
Validation Errors

HTTP Status: 400 Description: Request contains invalid or missing required parameters Solution: Check the details field for specific validation issues
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed for one or more fields",
    "details": [
      {
        "field": "customer_id",
        "message": "Customer ID is required"
      },
      {
        "field": "amount",
        "message": "Amount must be greater than 0"
      }
    ]
  }
}
HTTP Status: 400 Description: Date parameter is not in the expected format Solution: Use ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
{
  "error": {
    "code": "INVALID_DATE_FORMAT",
    "message": "Date must be in ISO 8601 format"
  }
}

​
Resource Errors

HTTP Status: 404 Description: The requested resource does not exist Solution: Verify the resource ID and ensure it exists
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Invoice with ID 'abc123' not found"
  }
}
HTTP Status: 409 Description: Attempting to create a resource that already exists Solution: Use PUT to update existing resource or check for duplicates
{
  "error": {
    "code": "RESOURCE_ALREADY_EXISTS",
    "message": "Invoice with this number already exists"
  }
}

​
Business Logic Errors

HTTP Status: 422 Description: Attempting to modify an invoice that has already been approved Solution: Only draft invoices can be modified
{
  "error": {
    "code": "INVOICE_ALREADY_APPROVED",
    "message": "Cannot modify an approved invoice"
  }
}
HTTP Status: 422 Description: Customer’s credit limit would be exceeded Solution: Increase credit limit or collect payment before proceeding
{
  "error": {
    "code": "INSUFFICIENT_CREDIT_LIMIT",
    "message": "Customer credit limit exceeded"
  }
}

​
Rate Limiting Errors

HTTP Status: 429 Description: Too many requests in a short time period Solution: Implement exponential backoff and respect rate limits
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "details": {
      "retry_after": 60,
      "limit": 100,
      "window": "1 hour"
    }
  }
}

​
Rate Limiting

The Upwell API implements rate limiting to ensure fair usage and system stability:
  • Standard Rate Limit: 100 requests per hour per API key
  • Burst Limit: 10 requests per minute
  • Rate Limit Headers: Check response headers for current limits
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 75
X-RateLimit-Reset: 1642248000

​
Error Handling Best Practices

​
1. Implement Retry Logic

async function apiCall(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API Error: ${error.error.message}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

​
2. Validate Input Data

def validate_invoice_data(invoice_data):
    required_fields = ['customer_id', 'amount', 'due_date']

    for field in required_fields:
        if field not in invoice_data:
            raise ValueError(f"Missing required field: {field}")

    if invoice_data['amount'] <= 0:
        raise ValueError("Amount must be greater than 0")

    # Additional validation logic...

​
3. Handle Specific Error Codes

import requests

def handle_api_response(response):
    if response.status_code == 200:
        return response.json()

    error_data = response.json().get('error', {})
    error_code = error_data.get('code')

    if error_code == 'INVALID_API_KEY':
        # Regenerate API key
        refresh_api_key()
    elif error_code == 'RATE_LIMIT_EXCEEDED':
        # Wait and retry
        retry_after = error_data.get('details', {}).get('retry_after', 60)
        time.sleep(retry_after)
    elif error_code == 'RESOURCE_NOT_FOUND':
        # Handle missing resource
        return None
    else:
        # Log unexpected error
        logger.error(f"API Error: {error_data.get('message')}")

    raise Exception(f"API Error: {error_data.get('message')}")

​
Getting Help

If you encounter persistent errors or need assistance:
  1. Check this documentation for common solutions
  2. Review API logs for detailed error information
  3. Contact support at [email protected]
  4. Include error details and request IDs when reporting issues
For urgent issues, please include:
  • API endpoint being called
  • Complete error response
  • Request timestamp
  • Your API key (last 4 characters only)