Test token validity

<overview> BigCommerce APIs return standard HTTP status codes with JSON error responses. Understanding common errors and implementing proper handling is crucial for reliable integrations. </overview> <statuscodes> <successcodes> | Code | Meaning | |------|---------| | 200 | OK - Request successful | | 201 | Created - Resource created | | 204 | No Content - Successful deletion | </successcodes> <clienterrors> | Code | Meaning | Action | |------|---------|--------| | 400 | Bad Request | Check request format and headers | | 401 | Unauthorized | Check credentials and token validity | | 403 | Forbidden | Check OAuth scopes and permissions | | 404 | Not Found | Verify that the resource exists; check the ID | | 405 | Method Not Allowed | Use the correct HTTP method | | 409 | Conflict | Resource state conflict; retry | | 413 | Payload Too Large | Reduce the request size | | 415 | Unsupported Media Type | Use application/json | | 422 | Unprocessable Entity | Check data validity, required fields | | 429 | Too Many Requests | Rate limited, implement backoff | </clienterrors> <servererrors> | Code | Meaning | Action | |------|---------|--------| | 500 | Internal Server Error | Retry with backoff | | 502 | Bad Gateway | Retry with backoff | | 503 | Service Unavailable | Retry with backoff | | 504 | Gateway Timeout | Retry with backoff | </servererrors> </statuscodes> <errorresponseformat> <standard_format> ``json { "status": 422, "title": "Unprocessable Entity", "type": "https://developer.bigcommerce.com/docs/start/about/status-codes", "errors": { "name": "Product name is required", "price": "Price must be a positive number" } } </standard_format> <graphql_errors> GraphQL always returns HTTP 200 with errors in body: json { "data": null, "errors": [ { "message": "Product not found", "locations": [{"line": 2, "column": 3}], "path": ["site", "product"] } ] } **Important:** All GraphQL errors return HTTP 401 status - check response body for details. </graphql_errors> </error_response_format> <common_errors> <error name="401-unauthorized"> **Causes:** - Expired access token - Invalid access token - Missing X-Auth-Token header - Wrong store hash **Diagnosis:** bash # Test token validity curl -X GET \ 'https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/summary' \ -H 'X-Auth-Token: {access_token}' \ -H 'Accept: application/json' **Solutions:** - Verify token is correct (no extra whitespace) - Check token hasn't expired - Regenerate credentials if needed - Verify store hash matches token </error> <error name="403-forbidden"> **Causes:** - OAuth scope insufficient - Resource belongs to different app - Store plan doesn't include feature **Diagnosis:** Check required scopes for endpoint in documentation. **Solutions:** - Add required OAuth scopes to API account - For apps: Re-authorize with expanded scopes - Contact merchant about plan features </error> <error name="404-not-found"> **Causes:** - Resource doesn't exist - Resource was deleted - Wrong resource ID - Typo in endpoint URL **Diagnosis:** bash # Verify resource exists GET /v3/catalog/products/{product_id} **Solutions:** - Verify ID is correct - Check if resource was deleted - Handle gracefully in code </error> <error name="422-unprocessable-entity"> **Causes:** - Missing required fields - Invalid field values - Data type mismatch - Business rule violation **Example:** json { "status": 422, "errors": { "weight": "Weight is required for physical products", "price": "Price must be greater than 0" } } **Diagnosis:** Review error messages - they specify which fields have problems. **Solutions:** - Add missing required fields - Validate data before sending - Check data types match schema - Review API documentation for constraints </error> <error name="429-rate-limited"> **Causes:** - Exceeded 20,000 requests/hour - B2B: Exceeded 150 requests/minute - Payments: Exceeded 50 requests/4 seconds **Headers to check:** X-Rate-Limit-Requests-Left: 0 X-Rate-Limit-Time-Reset-Ms: 1800000 X-Retry-After: 300 `` Solutions: - Implement exponential backoff - Respect the Retry-After header