Tester la validité du token

<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>

<status_codes>

<success_codes>

</success_codes>

<client_errors>

</client_errors>

<server_errors>

</server_errors>

</status_codes>

<errorresponseformat>

<standard_format>

{
  "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:

{
  "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>

</errorresponseformat>

<common_errors>

<error name="401-unauthorized">

Causes:

• Expired access token
• Invalid access token
• Missing X-Auth-Token header
• Wrong store hash

Diagnosis:

# 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:

# 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:

{
  "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 Retry-After header
• Optimize request patterns
• Use batching and caching

</error>

</common_errors>

<troubleshooting_auth>

<checklist>

1. Token format correct?

• No extra whitespace
• Complete token (not truncated)
• Using X-Auth-Token header (not Authorization)

1. Store hash matches token?

• Token is store-specific
• Check URL: /stores/{correct_hash}/

1. Token still valid?

• App tokens are permanent but can be revoked
• Storefront tokens expire

1. Required scopes present?

• Check API account scopes in control panel
• Match required scopes for endpoint

1. Clock sync?

• Server time must be accurate
• Use NTP for synchronization

</checklist>

<debugging_requests>

# Verbose curl to see all headers
curl -v -X GET \
  'https://api.bigcommerce.