Errors

Every error response has the same shape:

1
{
2
  "statusCode": 400,
3
  "message": "A human-readable explanation of what went wrong."
4
}

Status reference

Common scenarios

400 on create_claim

Most 400 responses are caused by:

• Missing user_email, registered_company_name, or country_code
• auth_sign_nationality not exactly 2 characters
• country_code not a valid ISO 3166-1 alpha-2 code

409 on create_claim

A KYB request for the same user_email + company combination already exists and isn’t in a rejected state. The response includes the existing request_id and its current status so you can surface the right message to your user.

400 on update_claim

Either the KYB request isn’t in approved status, or no updatable fields were provided besides request_id.

400 on resubmit_claim

Only KYB requests with status rejected can be resubmitted.

Retries

5xx responses are safe to retry with exponential backoff. 4xx responses indicate a client-side problem - fix the input before retrying.

On the webhook side

Your webhook endpoint should return 401 when signature verification fails. TREVEX will log the failure and retry with backoff - if your endpoint keeps rejecting valid signatures, check that:

• You’re using the raw request body, not a re-serialised JSON string
• You’re using the correct webhook signing secret for this Project
• Your clock is within the 5-minute timestamp tolerance
• You’re comparing with a constant-time function (Node: crypto.timingSafeEqual; Python: hmac.compare_digest)

See Verifying signatures for full examples.