Canva Error Classification
Overview
Treat HTTP status alone as insufficient. Use the current endpoint reference and redacted provider error code to separate caller defects, authorization failures, throttling, preview drift, and provider incidents.
Prerequisites
- HTTP status, provider error code, endpoint pattern, and UTC window
- Opaque request, resource, or job reference without payload content
- Pinned OpenAPI or endpoint documentation version
Instructions
Step 1: Capture a minimal envelope
Record method, endpoint pattern, status, provider code, terminal job state, retry metadata if actually present, and deployment version. Exclude tokens, bodies, signed URLs, and customer identifiers.
Step 2: Handle authentication failures
For an invalid or expired access token, serialize the authorized refresh flow and atomically store the replacement refresh token. Reauthorize after revocation or unrecoverable refresh failure.
Step 3: Handle authorization failures
Compare the operation with explicit granted scopes, resource ownership, capabilities, tenant policy, and preview availability. Never assume a write scope grants its read counterpart.
Step 4: Handle throttling
Pause only the affected endpoint/user queue. Use documented endpoint metadata and response instructions; otherwise apply bounded exponential backoff with jitter rather than a guessed fixed delay.
Step 5: Handle async failures
Poll the existing job to a documented terminal state. Correct validation or entitlement errors before any new submission.
Step 6: Escalate provider failures
Correlate repeated server errors with Canva status/changelog and provide a redacted support receipt after bounded retry is exhausted.
Authentication
Canva Connect calls use Bearer access tokens obtained by a backend through OAuth 2.0 Authorization Code with SHA-256 PKCE. Request explicit least-privilege scopes, keep client secrets and tokens out of browser-visible state, and serialize refresh so the replacement single-use refresh token is stored atomically.
Tool Discipline
Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Canva-side change.
Output
- Scoped decision or implementation artifact
- Redacted operation and validation receipt
- Failure, rollback, and follow-up ownership record
Examples
An autofill returns HTTP 403. The operator checks explicit scopes, current capability and Enterprise availability, template ownership, preview status, and the provider error before deciding whether reauthorization is relevant.
Error Handling
| Failure | Response |
|---|---|
| Only HTTP status is available | Collect the redacted provider envelope before acting |
| Refresh repeats 401 | Stop and require reauthorization instead of looping |
| 429 has no retry metadata | Use the local bounded backoff policy and lower concurrency |
| Job failed validation | Correct the request; do not retry unchanged input |