Troubleshooting

Quick solutions to common integration issues.

Order Creation Issues

"consumer is required"

Problem: You're missing the consumer object entirely.

Solution: Add a consumer object with either an existing ID or new consumer details:

{
  "consumer": {
    "first_name": "John",
    "last_name": "Doe"
  }
}

"last_name is required"

Problem: You provided first_name but not last_name.

Solution: When creating a new consumer, both names are required:

{
  "consumer": {
    "first_name": "John",
    "last_name": "Doe" // Required when first_name is provided
  }
}

"Either pack_id or contents required"

Problem: Your pouch object is empty or missing product information.

Solution: Each pouch needs either pack_id (for assemblies) OR contents (for custom orders):

Using Contents

{
  "pouches": [
    {
      "time_of_administration": "Morning",
      "contents": [{ "client_product_id": "your-product-uuid" }]
    }
  ]
}

Using Pack ID

{
  "pouches": [
    {
      "pack_id": "your-assembly-uuid",
      "time_of_administration": "Morning"
    }
  ]
}

warning

You cannot use both pack_id and contents in the same pouch.

"client_product_id must be a valid GUID"

Problem: The product ID is not a valid UUID format.

Solution: Product IDs must be valid UUIDs (e.g., d290f1ee-6c54-4b01-90e6-d701748f0851).

1. List your products: GET /v2/products
2. Copy the exact id value from the response
3. Use that ID in your order

"The following client products are inactive and cannot be ordered"

Problem: You're trying to order a product that has been deactivated.

Solution:

1. Check product status: GET /v2/products/{id}
2. Only use products where active: true
3. Filter your product list: GET /v2/products?active=true

"No Packaging Asset Group ID found for the order line"

Problem: Your client doesn't have packaging configured for this order.

Solution: Contact OK Capsule support. Packaging Asset Groups are configured during onboarding. You may need:

• A packaging design approved
• A default PAG assigned to your product line

Authentication Issues

"Token expired"

Problem: Your access token has expired (tokens expire after 24 hours).

Solution: Use your refresh token to get a new access token:

const response = await fetch(
  "https://na1-prod.okcapsule.app/v2/authentication/refresh-token",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refresh_token: yourRefreshToken }),
  }
);

const { access_token } = await response.json();

"Unauthorized" (401)

Problem: Missing, invalid, or expired token.

Checklist:

1. ✅ Is Authorization header present?
2. ✅ Does it start with Bearer (note the space)?
3. ✅ Is the token from the correct environment (stage vs prod)?
4. ✅ Has the token expired?

// Correct format
headers: {
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
}

"Forbidden" (403)

Problem: Your user doesn't have permission for this action.

Solution: Contact your admin to check your user's role and permissions in the client portal.

Environment Issues

Getting 404 errors

Problem: Using wrong base URL or endpoint path.

Solution: Verify you're using the correct environment:

Environment	Base URL
Production	https://na1-prod.okcapsule.app
Stage	https://na1-stage.okcapsule.app

warning

Stage and Production are completely separate. Credentials, products, and data do not transfer between environments.

"Stage credentials don't work in Production"

Problem: Trying to use stage credentials in production (or vice versa).

Solution: Each environment requires separate credentials. Contact OK Capsule to get credentials for both environments if needed.

Order Status Issues

"Order cannot be modified"

Problem: Trying to update an order that's already been accepted.

Solution: Orders can only be modified when status is Pending or On Hold. Once Accepted (after midnight PST processing), orders cannot be changed.

Check order status first:

const response = await fetch(
  `https://na1-prod.okcapsule.app/v2/orders/${orderId}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const { order } = await response.json();

if (order.status === "Pending" || order.status === "On Hold") {
  // Can modify
} else {
  // Cannot modify - contact support if needed
}

Order stuck in "Needs Changes"

Problem: Validation failed during order processing.

Solution: Check the order's notes for details:

1. GET /v2/orders/{id} - Check the note field
2. Common causes:
   • Inactive packaging design (PAG not approved)
   • Products no longer available
3. Fix the issue and create a new order

Debugging Checklist

When an API call fails:

1. Check HTTP status code - Different codes mean different issues
2. Read the full error response - The details array contains specific field errors
3. Verify request format - JSON must be valid, Content-Type header must be set
4. Check required fields - See Minimal Order Example
5. Verify IDs exist - Test with GET requests before using IDs in orders
6. Test in Stage first - Use stage environment for development

Getting Help

If you're still stuck:

1. Check the Interactive API Docs for endpoint details
2. Review Error Handling for error codes
3. Contact OK Capsule support with:
   • Request URL and method
   • Request body (redact sensitive data)
   • Full error response
   • Timestamp of the request