DocsPlatform & Reliability
Error Handling
Reference for standard API error codes, HTTP status codes, and Meta WhatsApp error code meanings.
4 min read•API v1
Standard API Error Codes
| Error Code | HTTP Status | Description & Resolution |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key Bearer token in Authorization header. |
| FORBIDDEN | 403 | API key has been revoked or access is denied to this workspace. |
| NOT_FOUND | 404 | The requested resource (message, contact, group, template) was not found. |
| VALIDATION_ERROR | 400 | Invalid payload parameters. Check details field for parameter issues. |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests. Check Retry-After header and throttle requests. |
| LIMIT_EXCEEDED | 403 | Plan daily template quota or contact limit reached. Upgrade required. |
| FEATURE_GATED | 403 | This feature (e.g. campaign scheduling) requires Growth/Pro plan. |
| CONFLICT | 409 | Idempotency-Key reuse with a different request payload body. |
| PAYLOAD_TOO_LARGE | 413 | Payload size exceeds 5MB or bulk array limit exceeds 500 items. |
| INTERNAL_SERVER_ERROR | 500 | Unexpected server error. Retry with backoff. |
Common Meta WhatsApp Error Codes
| Meta Code | Description | Resolution |
|---|---|---|
| 131047 | 24-hour service window closed | Must use an APPROVED template message instead of freeform text. |
| 131049 | Template does not exist or language mismatch | Verify exact template name and language code in /api/v1/templates. |
| 131056 | Positional variable count mismatch | Number of variables provided did not match template placeholder count. |
| 130429 | Rate limit hit on Meta API | Meta Cloud API rate limit. Automatically retried by PingStack worker. |