Mistakes

That guide describes the error code that can return APIs of JAAKand recommendations for their resolution.

Error response format

All error responses follow the same JSON format:

{
  "error": {
    "code": "invalid_token",
    "message": "The token's expired",
    "status": 401,
    "details": {
      "expiredAt": "2024-01-15T10:30:00Z"
    }
  }
}

---

HTTP status code

400 Bad Request

The request contains syntax errors or invalid parameters.

{
  "error": {
    "code": "invalid_request",
    "message": "The email field is required",
    "status": 400,
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

solution:

• Check that all required fields are present
• Check that data types are correct (string, number, etc.)
• Check that values are valid (email, URL, date) ISO 8601)

401 Unauthorized

The credentials are invalid or have been insufficient.

{
  "error": {
    "code": "invalid_credentials",
    "message": "API Key or API Invalid secret",
    "status": 401
  }
}

solution:

• Check that you're sending the right authentication headquarters
• Check that the credentials are right for the environment (sandbox vs. production)
• Check that tokens haven't expired.

403 Forbidden

You have no permission to have access to the requested remedy.

{
  "error": {
    "code": "forbidden",
    "message": "You have no permission to gain access to this remedy",
    "status": 403
  }
}

solution:

• Check that your plan includes access to this functionality
• Check that the user has the necessary permission
• Contact support if you think you should have access

404 Not Found

The requested remedy does not exist.

{
  "error": {
    "code": "not_found",
    "message": "Unfound meeting",
    "status": 404,
    "details": {
      "resourceType": "session",
      "resourceId": "ses_abc123xyz"
    }
  }
}

solution:

• Check that the remedy's ID is correct
• Check that the remedy exists in the right environment
• The remedy may have been removed or expired

422 Unprocessor Entity

The request is valid but cannot be processed due to business rules.

{
  "error": {
    "code": "session_already_completed",
    "message": "The sitting was completed and cannot be altered.",
    "status": 422,
    "details": {
      "sessionId": "ses_abc123xyz",
      "status": "completed"
    }
  }
}

solution:

• Check the current status of the remedy before trying to amend it
• Check documentation to understand valid status transitions

429 Too Many Requests

You have exceeded the limit of permitted applications.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded the demand limit. Try again in 60 seconds",
    "status": 429,
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "window": "1m"
    }
  }
}

solution:

• Implement exponential backoff into your code
• Backup the head Retry-After in response
• Consider packing responses as soon as possible
• Contact support if you need a bigger limit

500 Internal Server Error

Internal server error.

{
  "error": {
    "code": "internal_error",
    "message": "That's an internal mistake.",
    "status": 500,
    "details": {
      "requestId": "req_xyz789"
    }
  }
}

solution:

• Retry after a few seconds
• If the error persists, contact support with the requestId

---

Specific error codes

Authentication errors

Verification errors (KYC)

Signature errors (Signa)

Validation errors

---

Rate Limiting

The APIs of JAAK they implement demand limits to ensure service stability.

Default limits

Points limit heads

Each response includes leaders with border information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315200

Status limitation management

Implement exponential backoff when you get an error 429:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const retryAfter = error.details?.retryAfter || Math.pow(2, attempt);
        console.log(`Rate limited. Esperando ${retryAfter} segundos...`);
        await sleep(retryAfter * 1000);
      } else {
        throw error;
      }
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

---

Identification checks errors

These errors occur during the verification process and are reported in the result of the session.

document errors

Life errors

face match errors

Validation errors INE

---

Mapping your code

Full example

class JAAKError extends Error {
  constructor(response) {
    super(response.error.message);
    this.code = response.error.code;
    this.status = response.error.status;
    this.details = response.error.details;
  }
}

async function callJAAKAPI(endpoint, options) {
  const response = await fetch(`https://api.jaak.ai${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-API-Secret': API_SECRET,
      ...options.headers
    }
  });

  const data = await response.json();

  if (!response.ok) {
    throw new JAAKError(data);
  }

  return data;
}

// Using with bug management
async function createSession(verificationType) {
  try {
    const session = await callJAAKAPI('/api/v1/sessions', {
      method: 'POST',
      body: JSON.stringify({ verificationType })
    });
    return session;
  } catch (error) {
    if (error instanceof JAAKError) {
      switch (error.code) {
        case 'rate_limit_exceeded':
          console.log('Just waiting before we get back to it...');
          await sleep(error.details.retryAfter * 1000);
          return createSession(verificationType);

        case 'invalid_credentials':
          console.error('Invalid credentials. Check your API Key and Secret.');
          throw error;

        case 'forbidden':
          console.error('You have no access to this type of check.');
          throw error;

        default:
          console.error(`Error de JAAK: ${error.message} (${error.code})`);
          throw error;
      }
    }
    throw error;
  }
}

---

Contact Support

If you find an error that you cannot solve:

1. includes Request-Id response head
2. Describe the steps to play the bug
3. Includes error code and complete message
4. indicates the environment (sandbox or production)

Email: support

---

Following

• Webhooks - Configure real-time notifications
• Sandbox - Test your integration without affecting production