Errors

HTTP status codes the Humanos API returns, the error response shapes, and how to handle them

The Humanos API uses conventional HTTP status codes: 2xx for success, 4xx for problems with the request, and 5xx for problems on our side. Error responses are JSON.

Status codes

Code	Meaning	When you’ll see it
200 / 201	Success	The request completed; 201 on every successful POST, PATCH and DELETE.
400	Bad Request	Validation failed: a field is missing, has the wrong type, or an unknown field was sent (unknown fields are rejected, not ignored). See the validation shape below. Business-rule rejections, such as an invalid API-Version or an expired credential, also return 400, with a string message.
401	Unauthorized	Missing or invalid API key, or the request signature didn’t verify. Check both the Authorization header and the signature headers; see Authentication.
402	Payment Required	Your organization doesn’t have enough credits (POST /request, OTP resend).
403	Forbidden	The API key is valid but not allowed to perform this operation on this resource, or the operation was refused: a denied POST /credential/verify returns 403 with reason and evaluations, and OTP resend returns 403 when the request is canceled, expired, or out of resends.
404	Not Found	The resource doesn’t exist or doesn’t belong to your organization; the API deliberately doesn’t distinguish the two.
409	Conflict	The first request with this Idempotency-Key value hasn’t finished, or the value was already used for a different request. POST /request also returns it when two requests for the same contact race, and revoking a credential that is already revoked returns it too.
429	Too Many Requests	You hit a rate limit. Back off and retry; see Rate limits.
5xx	Server error	Something failed on our side. Retry GETs with backoff; for other calls, see the handling guidance below.

Validation errors (400)

Validation failures return a message array with one entry per failing field. Each entry names the field, echoes the offending value, and lists the violated constraints:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    {
      "field": "contact",
      "value": "not-a-contact",
      "constraints": {
        "contactValidation": "Contact \"not-a-contact\" is not a valid email or phone number"
      },
      "children": []
    }
  ]
}

Two behaviours worth knowing:

• Unknown fields are rejected. The API whitelists the documented fields for each endpoint; sending anything else fails the request rather than being silently dropped. This catches typos (internalid vs internalId) at the door.
• Nested objects report through children. When a nested field fails, the parent entry’s children array carries the nested validation errors, each naming the inner field under a property key, with its own constraints (and deeper children if the nesting continues).

Authentication errors (401)

401 responses carry a short message identifying which layer failed:

{
  "statusCode": 401,
  "message": "Invalid signature",
  "error": "Unauthorized"
}

Work through the layers in order: is the Authorization: Bearer <api-key> header present and correct → is the signature computed over the compact JSON body (exactly the JSON.stringify output you send) with the right secret → is the timestamp fresh. The SDK signs every request automatically, which eliminates the most common cause.

Handling guidance

• Don’t retry 400/401/403: the request will fail the same way until you change it.
• Treat 404 as “not visible to me”, not proof of non-existence.
• Retry 429 after waiting the number of seconds in the Retry-After header (up to 60). See Rate limits.
• Retry 5xx GETs with backoff. For other calls, send an Idempotency-Key where the endpoint accepts one (POST /request, PATCH /request/resend/{requestId}, POST /user). Retrying with the same value is then safe: for 24 hours, a repeat returns the original response instead of running again. A 503 with a Retry-After header on such a call means nothing ran, so retry with the same value after that many seconds. Without a key, check state first (e.g. GET /request/{id}) before re-sending, so you don’t create duplicates.
• Retry a 409 with the same Idempotency-Key value after a short wait. The first request with that value hasn’t finished yet (this clears within five minutes), or, on POST /request, two requests for the same contact raced. The exception: if the message says the value was already used with a different request payload, you reused a value for another request. Send that request with a new value.