Errors & troubleshooting

This page covers what to expect when a request fails: the HTTP status codes the API uses, the most common reasons each one is returned, and a checklist for debugging HMAC signing — the source of the majority of integration support tickets.

HTTP status codes

Status	Meaning	Most common cause
200	OK	Request succeeded.
201	Created	Resource successfully created (e.g. POST /public/users).
400	Bad Request	Malformed JSON, missing required field, or a field value that fails validation.
401	Unauthorized	Authorization header missing, malformed, signature does not verify, or Date header outside accepted skew.
403	Forbidden	Credentials are valid, but the underlying user is not an admin of the Instance — or the role lacks permission.
404	Not Found	Wrong path (check the /api/5/ prefix), or the referenced resource (userId, token) does not exist.
409	Conflict	A resource with the same unique attribute already exists (most often a duplicate email on POST /public/users).
429	Too Many Requests	Rate limit reached. Back off and retry — see Rate limits below.
5xx	Server error	Transient server-side issue. Retry once with a small delay before escalating.

Error response shape

Errors return a JSON body with at least a human-readable message. The exact fields may vary by endpoint, but partners can rely on this shape at minimum:

Example 400 response

{
  "message": "Field 'email' must be a valid email address.",
  "status": 400
}

Treat anything beyond message and status as informational only — do not parse error text to drive control flow. Branch on the HTTP status code.

Debugging authentication

401 with a WEVSIMPLE secret

1. Check the header literal — it's Authorization: WEVSIMPLE <secret>, with one space, no Bearer, no quotes.
2. Confirm you're sending the secret you were issued, not the API key (HMAC integrations have both — only the secret authenticates).
3. Confirm you're hitting https://www.wevideo.com/api/5/ and not a stale internal host.

401 with a WEV (HMAC) signature

This is the most common integration failure. Work down the list:

1. Date header in UTC. A Date more than a few minutes off from the server's clock will be rejected. Format must look like Wed, 16 Jul 2014 16:50:40 UTC. If you're computing the date in local time, fix that first.
2. The Date header value and the value used in StringToSign must be byte-identical. Generate the string once and reuse it.
3. MD5 the exact request body. If you serialize JSON twice (once for hashing, once for sending) and the two serializations differ — different key order, whitespace, escaping — the signature will not verify. Hash the bytes you actually send.
4. For empty bodies (any GET), MD5 is d41d8cd98f00b204e9800998ecf8427e — the MD5 of the empty string. Do not skip this term in StringToSign.
5. StringToSign is the full URL, not just the path. Use https://www.wevideo.com/api/5/public/users, not /public/users.
6. Include query-string parameters in the URL used for signing, in the exact form they appear on the wire (same encoding, same order).
7. The signature is base64 of the raw HMAC-SHA256 bytes — not hex, not base64-of-hex. Most language defaults are correct; double-check if you're getting consistent 401s.
8. No trailing whitespace or newlines in StringToSign, the URL, or the Date. Logging StringToSign and comparing across machines is the fastest way to find these.

If you've checked all of the above and still get 401, log your StringToSign and the resulting Authorization header from a single failing request and send them to support@wevideo.com — that's enough for the team to identify the mismatch.

403

The credentials authenticated successfully, but the underlying user does not have permission for the operation. Most public endpoints require an Instance admin. If you believe the user should be an admin, confirm the role assignment in the Instance — admin status is per-Instance, not global.

Rate limits

The public API may apply rate limits on a per-credential basis. If you exceed a limit, you'll receive HTTP 429. You should:

• Treat 429 as a normal, recoverable response — never as a fatal error.
• Implement exponential backoff with jitter; a sensible starting point is 1s → 2s → 4s with up to 5 retries.
• Avoid tight loops over user lists or tokens — batch where possible and respect the Pageable pagination on list endpoints.

If you expect sustained high request volume (bulk user provisioning, large data backfills), contact support before launch so we can confirm the integration won't hit limits at scale.

Retries and idempotency

• GET requests are safe to retry on any network error or 5xx.
• POST requests are not automatically idempotent. Retrying POST /public/users after a timeout may create a duplicate. Always check whether the user already exists (e.g. via GET /public/users?query=<email>) before retrying a creation that timed out.
• For login-token issuance, retrying is safe — old tokens simply remain unconsumed and expire on their own.

Getting help

If you're stuck, contact support with:

1. The request method and full URL.
2. The request headers, with the secret/key redacted.
3. The full response status and body.
4. (HMAC only) The StringToSign you computed.

That set of four reproduces almost any auth or validation issue on the first reply.