XipID API errors

A refusal answers one body, whatever its code: {"error": {...}} with the code to branch on, a sentence for a person, one entry in details for each problem with the request, the request's id, and this site's page for the code. A code may carry members of its own, which its page names.

• code string, one of the codes below

  What went wrong, for a client to branch on; each code's page is at doc_url.

• message string

  XipID's sentence, for a person; never branch on it.

• details array of object

  One entry for each problem with the request.

  • path string

  • code string, one of the values below

    What is wrong with the member.

    • required: It is missing.
    • unknown: The route does not take it.
    • invalid_type: It is of another type.
    • invalid_format: It is not in the format it must be in.
    • invalid_value: It is none of the values it may be.
    • too_small: It is under its minimum.
    • too_big: It is over its maximum.

  • message string

• request_id ULID

  The request, as X-Request-Id names it.

• doc_url string

  The code's page.

• valid_versions array of string, optional

  Carried by version_invalid.

• challenge_id ULID, optional

  Carried by text_failed, subject_unlinked, consent_missing.

• provider string, optional

  Carried by text_failed, email_failed.

• provider_code integer, optional

  Carried by text_failed.

• pairwise_id pairwise identifier, optional

  Carried by subject_unlinked, consent_missing, channel_unavailable, reference_face_missing.

• reason string, one of the values below, optional

  Carried by reference_face_unusable.

  • unsupported_format: The image is neither a JPEG nor a PNG.
  • no_face: The image holds no face.
  • multiple_faces: The image holds more than one face.

• attempts_left integer, at least 0, optional

  Carried by code_invalid.

• try_again_at instant, RFC 3339, optional

  Carried by code_resend_too_soon, selfie_limit_reached, document_limit_reached.

Every code

• json_invalid, 400: The request body is not valid JSON.
• parameter_missing, 400: The request lacks a required parameter.
• parameter_invalid, 400: The request contains invalid parameters.
• parameter_unknown, 400: The request contains a parameter this route does not take.
• idempotency_key_missing, 400: This route requires an Idempotency-Key header.
• version_invalid, 400: Xip-Version names no released version of this API.
• cursor_invalid, 400: The cursor is malformed or belongs to another list.
• authentication_required, 401: Authentication is required.
• authentication_failed, 401: The credential is invalid, expired or revoked.
• insufficient_scope, 403: The credential does not allow this operation.
• resource_not_found, 404: No such resource.
• method_not_allowed, 405: This path does not take that method.
• resource_conflict, 409: The resource's state conflicts with the request; read it again.
• idempotency_key_in_use, 409: The first request with this Idempotency-Key is still running.
• endpoint_removed, 410: This endpoint was removed at its sunset.
• precondition_failed, 412: If-Match does not match the resource's current ETag.
• content_too_large, 413: The request body is larger than this route accepts.
• media_type_unsupported, 415: This route does not accept that Content-Type.
• idempotency_key_reused, 422: This Idempotency-Key was used for a different request.
• precondition_required, 428: This route requires an If-Match header.
• rate_limit_exceeded, 429: Too many requests; try again later.
• internal_error, 500: Something went wrong on our side.
• upstream_error, 502: A service XipID depends on failed.
• service_unavailable, 503: The service is temporarily unavailable.
• upstream_timeout, 504: A service XipID depends on did not answer in time.
• challenge_closed, 409: The challenge is already closed.
• invitation_changed, 409: The brand changed what it asks after the invitation was read.
• delegation_changed, 409: The agent's request changed or closed after it was read.
• agent_version_taken, 409: An agent of the org has that key and version.
• subject_scopes_accepted, 409: The person accepted the scopes first asked, and asking for others needs their consent again.
• brand_slug_taken, 409: A brand with that slug exists.
• email_reserved, 409: The address belongs to a XipID staff account.
• reference_face_on_file, 409: The person has a face on file that this brand did not enroll, and it stays.
• subject_unlinked, 422: The pairwise identifier names no person linked to this brand, or to a brand of this agent's org.
• consent_missing, 422: The person has not granted this brand, or this agent, their presence.
• channel_unavailable, 422: The person has no phone XipID may text.
• reference_face_missing, 422: The person has no face on file.
• reference_face_unusable, 422: The image cannot be a reference face.
• callback_url_refused, 422: No outcome can be posted to that callback URL.
• text_failed, 422: The provider refused the text.
• email_failed, 422: The provider refused the email.
• code_invalid, 422: That code is not right.
• code_expired, 422: The code expired or has no tries left.
• code_used, 422: The code was already used.
• code_resend_too_soon, 422: A code was sent too recently to send another.
• registration_expired, 422: The registration expired.
• test_identity_refused, 422: The address or number is reserved for testing, which production refuses.
• link_expired, 422: The request the link opens is closed.
• link_used, 422: The link was already opened in another browser.
• decline_not_allowed, 422: The request's policy does not allow a decline.
• selfie_limit_reached, 422: The hour's selfies are used up.
• document_limit_reached, 422: The day's document reads are used up.
• owner_required, 409: The org must keep an owner: hand the ownership to another member first.
• member_exists, 409: That XipID is already a member of the org.
• member_invitation_closed, 422: The invitation was accepted, was withdrawn, or is past its 7 days.
• member_invitation_other_address, 422: The invitation went to another address than the one this XipID verified.