Skip to content
  • There are no suggestions because the search field is empty.

Troubleshooting The DNA Behavior API: Common Errors And Fixes

This guide covers common errors encountered when making requests to the DNA Behavior API, along with their causes and fixes.

1. 401 Unauthorized

The most common error. Means the API did not accept your credentials.

Check the following:

  • The subscription key is being passed in the request header, not the URL. The correct header is Ocp-Apim-Subscription-Key.
  • The subscription key belongs to the correct account. Keys are account-specific and are not interchangeable across accounts.
  • The key has not been rotated or revoked. If you recently regenerated your key in the Developer Portal, any integrations still using the old key will return 401.
  • If you are using a hosting platform like Vercel, confirm that your security headers are not stripping custom request headers before the request reaches the API. This has been identified as a root cause in some deployments.

2. 403 Forbidden

The request was authenticated but the account does not have permission to access the requested resource.

Check the following:

  • The accountId in the request matches the account associated with your subscription key.
  • Your plan or license includes access to the endpoint you are calling. Some endpoints are restricted by plan tier.
  • If you are an ISV with multiple accounts, confirm you are using the correct key and account ID combination for the specific request.

3. 404 Not Found

The resource you are requesting does not exist, or the user has not yet completed their discovery.

Before calling result endpoints such as GetAssessmentResults, GetBDNA5Scores, GetFDNA5Scores, or any insights endpoint, use the following to confirm the user is ready:

  • CheckIfParticipantExists to confirm the user exists in the platform under the given username.
  • GetDiscoveryStatus to confirm the user has completed their discovery. Many result endpoints return 404 if the profile is incomplete rather than returning an empty response.

Also check:

  • The PersonID, accountId, or other identifier in the request is correct.
  • The endpoint URL matches the Developer Portal exactly. Pay attention to casing and path structure.

4. 400 Bad Request

The request was malformed or missing required fields.

Check the following:

  • All required parameters are present in the request body or query string.
  • Data types match what the API expects. Passing a string where an integer is required will trigger a 400.
  • The request body is valid JSON and the Content-Type header is set to application/json.

5. InsertParticipantInAccount Failing

This endpoint is typically called early in the integration flow to register a participant. Common failure causes:

  • The email address is already registered under the account. The DNA platform treats each email as a unique record. Attempting to insert a duplicate will fail.
  • Required fields are missing or incorrectly typed in the request body.
  • The accountId does not match the account associated with your subscription key.

If you need to check whether a participant already exists before inserting, call CheckIfParticipantExists first.

6. Insert11Q17QAnswers or SubmitAnswers Failing

These endpoints handle answer submission for the short-form and full discovery flows respectively.

Check the following:

  • The PersonID and CreditID returned from InsertParticipantInAccount are being passed correctly. These are required to associate answers with the correct participant record.
  • The questionPattern matches the answer set you are submitting. Submitting 11-question answers against a 46-question pattern will fail.
  • All answers are present and correctly formatted. Partial answer submissions will be rejected.

7. 500 Internal Server Error

An error occurred on the API side. This is not caused by your request structure.

If you receive a 500:

  • Retry the request. Transient server errors will typically resolve on their own.
  • Check the DNA Behavior status page to see if there is an ongoing incident.
  • If the error persists across multiple retries, submit a support ticket with the endpoint you are calling, your accountId, and the timestamp of the failed request. Do not include your subscription key.

8. Webhook Payload Not Being Received

If you are not receiving webhook notifications after a user completes their profile:

  • Confirm your webhook URL is registered and the status is set to true. Use GetWebhookURLByAccountId to verify.
  • Ensure your webhook endpoint is publicly accessible. Local development URLs will not receive payloads.
  • Check that your server returns a 200 OK response. If the DNA API does not receive a 200, it may not retry delivery.
  • Review your server logs for the exact timestamp of the discovery completion to confirm whether the payload was sent but rejected.

If you suspect payloads were missed, use WebhookSync to manually trigger a sync for a specific participant, or WebhookSyncAll to sync all completed profiles for your account. These are useful recovery tools if your endpoint was temporarily unavailable.

9. Responses Returning Stale or Incorrect Data

If API responses are returning data that does not reflect recent changes:

  • Confirm you are querying the correct accountId and PersonID.
  • If you are caching API responses on your end, check whether the cache has expired and is serving old data.
  • Allow a short processing window after discovery completion before querying results. Score calculation happens asynchronously and results may not be immediately available.

Still stuck?

Submit a support ticket here. Include the endpoint you are calling, your accountId, the HTTP status code you are receiving, and any response body returned. Do not include your subscription key or encryption key in the ticket.