Request Rate Limits

These limits control the number of requests you can make in short time intervals and are applied per API key.

Monitoring Usage via Headers

The API response headers provide real-time information about your current limits. Use these to build robust, adaptive integrations.

            X-RateLimit-Limit: 100
            X-RateLimit-Remaining: 95
            X-RateLimit-Reset: 1640995200

            X-API-Requests-Used: 500
            X-API-Requests-Limit: 10000
            X-API-Requests-Remaining: 9500

Validate Before Submission

Replace /api/v1/ with /api/v1/test/ and send the same JSON or multipart request. Test mode checks authentication, inbox ownership, the template, and any uploaded file, but does not call Meta.

Validation errors identify the exact field and suggest how to fix it:

{
  "success": false,
  "api_version": "1.0.0",
  "error": {
    "code": "TEMPLATE_VALIDATION_FAILED",
    "message": "The WhatsApp template payload is invalid",
    "details": "1 validation error(s) found. Fix validation_errors and retry.",
    "validation_errors": [
      {
        "field": "components[0].text",
        "code": "PARAMETERS_WORD_RATIO_EXCEEDED",
        "message": "Body has 5 non-variable word(s) for 3 variable(s); Meta requires at least 7.",
        "suggestion": "Add at least 2 descriptive non-variable word(s), or remove variables."
      }
    ],
    "template_help": {
      "description": "Use sequential numbered variables, realistic examples, and at least 2P + 1 non-variable body words for P variables."
    }
  }
}

• Numbered variables must be sequential and have matching, non-empty examples.
• Named variables require parameter_format: "NAMED" and matching named examples.
• A body with P variables needs at least 2P + 1 non-variable words.
• Header, footer, buttons, authentication, OTP, and TTL rules are checked before submission.

Success Response

Production returns HTTP 201 when Meta accepts the template for review.

{
  "success": true,
  "api_version": "1.0.0",
  "data": {
    "template_id": "123456789",
    "template_name": "order_ready",
    "template_category": "UTILITY",
    "language": "en_US",
    "status": "PENDING",
    "submitted_at": "2026-08-04T12:00:00.000Z",
    "meta_response_details": {
      "id": "123456789",
      "status": "PENDING",
      "category": "UTILITY"
    }
  },
  "message": "WhatsApp template submitted successfully"
}

Media Validation Process

When you provide a media_url, we perform a series of checks to ensure the file is valid and secure before sending it.

Sandbox Environment

Every production endpoint has a corresponding test endpoint. To use it, simply insert /test into the URL path. You can also try both modes interactively with the Try It console shown next to every endpoint in this documentation.

For template creation, test mode performs full local template and media validation but never uploads the file or submits the template to Meta.

Development Checklist

Follow these best practices to ensure a smooth and reliable integration.

• Use Test Endpoints First: Always validate your requests against the sandbox before deploying to production.
• Handle Rate Limits Gracefully: Implement exponential backoff when you receive a `429` error to avoid being blocked.
• Parse Error Details: Don't just check for success/failure. Use the `code` and `template_help` objects in error responses to debug effectively.
• Secure Media URLs: Ensure all `media_url` links are public, directly accessible, and use HTTPS.
• Monitor Usage Headers: Keep an eye on `X-API-Requests-Remaining` to stay within your monthly plan limits.

Final Best Practices