Skip to main content
The Braintest API uses standard HTTP status codes and a consistent JSON error envelope. This page explains what each status means, shows the exact response shape, and provides guidance for resolving the most common errors.

​
HTTP status codes

​
Error response envelope

All error responses follow the same envelope structure as successful ones:
  • data: always null on error
  • successful: always false on error
  • messages: array of human-readable error strings; may contain multiple messages

​
Common 400 errors

A 400 response means the request syntax or parameters are invalid. Common causes include: Invalid mobile number
Mobile numbers must be exactly 11 digits and start with 09. Invalid filter parameter
Check that query filters like filter__is_finished use boolean strings (true or false). Missing required profile field
Ensure all required profile fields (name, mobile, birth, is_male) are present and valid.

​
401 vs 403

These two statuses both indicate access problems, but the cause and fix differ. 401 Unauthorized The API-KEY header is missing or the key does not exist.
What to check:
  • The header name is exactly API-KEY
  • The value matches the key generated in the organizer panel
  • The key is active and has not been revoked
403 Forbidden The key is valid, but the request is blocked for another reason.
Common causes:
  • The API key is expired or suspended
  • The requesting IP address is not allowlisted
  • A payment or quota issue exists on the account
  • The record or roadmap requires profile authentication first (auth_required: true)

​
409 conflicts

A 409 response means the resource is in a state that prevents the requested operation. Already completed
You cannot re-authenticate or re-submit answers for a finished record. Duplicate external_id
The external_id must be unique per organizer. Choose a different value. Roadmap record authentication error
You called /record/{token}/auth/ for a record that is part of a roadmap. Use /roadmap/{token}/auth/ instead. Incomplete roadmap
Finish every test record in the roadmap before calling /roadmap/{token}/generate/.

​
Rate limits

The Braintest API enforces per-minute and per-hour request limits on every API key. When you exceed either limit, the API returns HTTP 429 Too Many Requests. See Rate Limits for the exact values and handling guidance.

​
General troubleshooting tips

  1. Always check the messages array first. It contains the most specific explanation.
  2. Verify the base URL is https://braintest.ir/api/v2/ and the path is correct.
  3. Confirm the API-KEY header is present and properly formatted.
  4. For 400 errors, validate your JSON body against the field requirements in the relevant guide.
  5. For 409 errors, check the current resource status before retrying the operation.