C.O.G.N.I.T. API Docs

A C.O.G.N.I.T. API which powers C.O.G.N.I.T. website

Errors

Source of truth: backend app.config.ERROR_CODES. Build client behavior around error.code, and keep error.request_id for support and trace correlation.

AUTH

  • AUTH_001_0001 HTTP 403
    Please agree to the consent terms to continue.
  • AUTH_001_0002 HTTP 403
    Your account has been flagged. Contact support.
  • AUTH_003_0001 HTTP 403
    Invalid verification code. Please try again.
  • AUTH_003_0002 HTTP 410
    Verification code expired. Request a new one.
  • AUTH_003_0003 HTTP 429
    Too many attempts. Request a new verification code.
  • AUTH_003_0004 HTTP 404
    No verification code found. Please request a new one.
  • AUTH_003_0005 HTTP 503
    Email service is temporarily unavailable. Please try again in a minute.
  • AUTH_003_0006 HTTP 403 (field: email)
    Email does not match your registration details.
  • AUTH_003_0007 HTTP 400 (field: email)
    Please enter a different email address to update.
  • AUTH_003_0009 HTTP 504
    Email service took too long to respond. Please try again.
  • AUTH_003_0010 HTTP 503
    Email service returned an error. Please try again.
  • BOT_001_0002 HTTP 403
    Human verification failed while creating the participant. Please retry.
  • BOT_001_0005 HTTP 403
    Human verification failed while submitting the response. Please retry.

DUP

  • DUP_001_0001 HTTP 409 (field: username)
    This username is already taken.
  • DUP_001_0002 HTTP 409 (field: email)
    This email is already registered.
  • DUP_001_0004 HTTP 409
    You have already registered.
  • DUP_002_0001 HTTP 409
    You have already described this image.
  • DUP_002_0002 HTTP 409
    You have already completed this survey round.

NF

  • NF_001_0005 HTTP 404
    Route not found.
  • NF_001_0006 HTTP 404
    No images are currently available. Please try again later.
  • NF_001_0012 HTTP 404
    Participant not found while recording consent.
  • NF_001_0014 HTTP 404
    Participant not found while submitting the response.

RATE

  • RATE_001_0001 HTTP 429
    Too many attempts. Please wait a moment.

SYS

  • SYS_001_0001 HTTP 500
    Something went wrong. Please try again.
  • SYS_001_0002 HTTP 500
    Database error occurred. Please try again later.
  • SYS_002_0024 HTTP 503
    Service degraded.
  • SYS_002_0030 HTTP 500
    Failed to select a fallback image.
  • SYS_002_0031 HTTP 500
    Failed to load the next image. Please try again.
  • SYS_002_0035 HTTP 500
    Failed to check username availability. Please try again.
  • SYS_002_0036 HTTP 500
    Failed to check email availability. Please try again.
  • SYS_002_0037 HTTP 500
    Failed to record consent. Please try again.
  • SYS_002_0039 HTTP 500
    Failed to load participant options. Please try again.
  • SYS_002_0040 HTTP 500
    Failed to request email verification code. Please try again.
  • SYS_002_0041 HTTP 500
    Failed to verify email code. Please try again.
  • SYS_002_0042 HTTP 500
    Failed to save submission. Please try again.

VAL

  • VAL_001_0002 HTTP 400 (field: email)
    Please enter a valid email address.
  • VAL_001_0004 HTTP 400 (field: age)
    Age must be between 13 and 100.
  • VAL_001_0005 HTTP 400 (field: gender_code)
    Please select a gender.
  • VAL_001_0007 HTTP 400 (field: language_code)
    Please select your native language.
  • VAL_001_0008 HTTP 400 (field: prior_experience)
    Please select your prior experience.
  • VAL_002_0001 HTTP 400 (field: description)
    Description must be 60-10000 characters long.
  • VAL_002_0004 HTTP 400 (field: description)
    At least 60 words are required.
  • VAL_002_0005 HTTP 400 (field: feedback)
    Feedback must be 5-2000 characters long.
  • VAL_002_0008 HTTP 400 (field: ratings)
    Difficulty and confidence ratings must be between 1 and 10.
  • VAL_003_0003 HTTP 400
    Invalid request ID format.
  • VAL_003_0007 HTTP 405
    This action is not available here.
  • VAL_003_0008 HTTP 400 (field: image_id)
    Invalid image identifier.
  • VAL_003_0009 HTTP 409
    Idempotency key reuse with a different request payload is not allowed.
  • VAL_003_0010 HTTP 400 (field: X-Idempotency-Key)
    Missing required X-Idempotency-Key header.
  • VAL_003_0011 HTTP 400 (field: X-Idempotency-Key)
    X-Idempotency-Key must be <= 128 characters.
  • VAL_003_0016 HTTP 400 (field: general)
    Participant creation is missing required fields.
  • VAL_003_0017 HTTP 400 (field: username)
    Username is required.
  • VAL_003_0018 HTTP 400 (field: email)
    Email is required.
  • VAL_003_0019 HTTP 400 (field: public_id)
    Public ID is required to record consent.
  • VAL_003_0021 HTTP 400 (field: general)
    Public ID and email are required to request an email verification code.
  • VAL_003_0022 HTTP 400 (field: general)
    Public ID, email, and verification code are required.
  • VAL_003_0023 HTTP 400 (field: public_id)
    Public ID is required to submit a response.
  • VAL_003_0024 HTTP 400 (field: image_id)
    Image ID is required to submit a response.
  • VAL_003_0025 HTTP 409 (field: stage)
    Participant is not in a valid stage for this action. 
{
  "success": false,
  "error": {
    "code": "BOT_001_0002",
    "message": "Human verification failed while creating the participant. Please retry.",
    "category": "AUTH",
    "http_status": 403,
    "retryable": false,
    "request_id": "6d1902a2-9f91-41da-b3df-128565f4bdb3",
    "details": {}
  }
}
C.O.G.N.I.T