Application API Failure Codes

October 15, 2026 at 9:35 AM

Failure Codes

This page documents all of the failure codes we return in the API along with rules about how they are designed. Note that the list duplicates information in the main API documentation pages but it gathers all the codes in numerical order so the structure is easier to see.

When we have only one API parameter to validate (or the possible failures are very simple), we tend to only return status 403 Forbidden with fail set to "Invalid Argument" and no failcode. When multiple parameters are being validated, we return a failcode array containing a failure code for each validation that fails (note that we might not validate every parameter if some validation has already failed).

In general the codes are x0y0z where x represents the “API Group”, y represents the parameter, and z represents the specific validation failure for parameter y. There are some exceptions. Photo validations are 11y0z, for example. In general, y is the order in which the parameters are documented (or were originally documented) and therefore required parameters come first, then optional ones. They probably should have been in alphabetical order within those two groups but…

Adding new API Groups will be carefully considered since we only have 80 and 90 left unless we start using xx instead of x0 values. API Groups shouldn’t have more than nine distinct validated parameters (otherwise we should rethink the APIs!) so new parameter numbers can be added sequentially along with validation numbers on each of those.

Registration (mainly) but also Profile Update

  • 10000 - unknown field - check spelling
  • 10001 - gender is not valid (not "Male" or "Female")
  • 10002 - genderpreference is not valid (not "Male" or "Female")
  • 10011 - country is not valid
  • 10021 - firstname is empty or too long (limit 100)
  • 10022 - lastname is empty or too long (limit 100)
  • 10031 - latitude is not a valid latitude
  • 10032 - longitude is not a valid longitude
  • 10041 - zip is empty or too long (limit 20)
  • 10051 - city is empty or too long (limit 255)
  • 10061 - state is empty or too long (limit 45)
  • 10101 - username already in use
  • 10102 - invalid username (contains illegal characters)
  • 10201 - password minimum length and/or other restrictions not met
  • 10301 - invalid email address (incorrect format)
  • 10302 - email address already in use
  • 10401 - invalid dateofbirth format
  • 10402 - minimum age requirement not met (dateofbirth)
  • 10501 - headline is empty or too long (over 75 characters)
  • 10601 - aboutme is empty or too long (over 1,500 characters)
  • 10701 - affiliate is suspended - call /recordaffiliatehit to obtain redirect URL

Photo Handling

  • 11201 - image / imageurl missing (at least one must be provided)
  • 11202 - both image and imageurl are present (only one may be provided)
  • 11203 - member already has their maximum number of uploaded photos
  • 11204 - we were unable to process the image after it was uploaded (for an unspecified reason)
  • 11205 - the image was too large (we cap at around 5MB)
  • 11206 - the image was not an acceptable type (BMP, GIF, ICO, JPG, PNG)
  • 11301 - if photoid is missing
  • 11302 - if photoid is not numeric
  • 11303 - if a photo identified by photoid does not exist or does not belong to this member

Profile Update

  • 20101 - invalid value for gender
  • 20102 - member has exceeded allowable number of gender changes
  • 20201 - invalid value for country
  • 20301 - invalid value for zip (or zippostalcode)
  • 20401 - invalid dateofbirth (not a valid date value)
  • 20402 - member has exceeded allowed number of dateofbirth changes
  • 20403 - minimum age requirement not met
  • 20501 - email is not valid email address
  • 20502 - email is already in use on this site
  • 20701 - display_name_preference should be "nickname" or "firstname"
  • 20702 - online should be true or false
  • 20703 - world_plus should be "opted-in", "opted-out", or "undecided"
  • 20704 - deactivated should be true or false
  • 20801 - setting is not valid
  • 20901 - value(s) provided are out of range (for the parameter’s expected list of values)

Saved Searches

  • 20222 - name was not provided
  • 20223 - name was empty or too long (limit 32)
  • 20224 - id was provided (other APIs do accept id however)
  • 20225 - A saved search with this name already exists

Match Criteria v1

  • 30101 - distance is invalid
  • 30201 - only one age provided (agefrom/ageto)
  • 30202 - age is not numeric
  • 30203 - age range is invalid (should be 18-120)
  • 30301 - lookingfor is invalid (not "Male" or "Female")
  • 30401 - zippostalcode is invalid (for the given country)
  • 30501 - country is invalid

Search / Search Criteria v2

  • 31000 - the criterion value is ill-formed (not a hash map)
  • 31003 - a general criterion value does not contain either value or values
  • 31004 - a range criterion value does not contain to and from, or their values are not numeric, or the from value is higher than the to value
  • 31005 - an age range criterion value has to and/or from values outside the range 18..120
  • 31006 - a geolocation criterion does not contain within and of values, or the within value is not a numeric value from the set -1, 20, 30, 40, 50, 150, 500, 1000
  • 31007 - a geolocation criterion has a within value of 20, 30, 40, or 50 but the member is not platinum (only platinum members can specify those smaller distances)
  • 31008 - the criterion is only available to platinum members (the current member is not a subscriber)
  • 31009 - the criterion value(s) specified are not legal for this criterion (e.g., 50 for smoking, which only has 10, 20, 30, and 40 as legal values)
  • 31010 - the country criterion value is illegal (not a valid two-letter ISO code)
  • 31011 - the zipcode criterion value is illegal (for the member’s country)
  • 31012 - the age criterion is missing: it is required for all searches
  • 31013 - only one of zipcode, state, or location may be provided (they are both optional but they are mutually exclusive)

Search v1

  • 40101 - distance is invalid
  • 40201 - only one age provided (agefrom/ageto)
  • 40202 - age is not numeric
  • 40203 - age range is invalid (should be 18-120)
  • 40301 - lookingfor is invalid (not "Male" or "Female")

Interaction Limits

  • 50001 - maximum number of likes per day exceeded

Messaging/Profile Access

Since there is a great deal of overlap with the “can access profile” logic here, some of these are also returned by the GET /users/* and POST /like APIs as well.

  • 80001 - self send
  • 80002* - gender preferences do not match
  • 80003* - receiver deleted
  • 80004* - receiver has blocked sender
  • 80005 - sender has blocked receiver
  • 80006 - receiver is (not searchable, or not approved, or rejected) and has not messaged sender and is not a connection
  • 80007* - sender and receiver are not in the same equivalence and recipient is not opted into world+
  • 80008 - member is not platinum (messaging 3.0)
  • 80009+ - sender is over limit
  • 80010+ - sender cannot send to receiver’s country
  • 80011+ - sender has not uploaded photos
  • 80012 - sender doesn’t exist
  • 80013 - receiver doesn’t exist
  • 80014* - receiver suspended
  • 80015 - receiver is admin
  • 80016 - failed to store message; should be rare, best policy on reciept is to retry.

Codes marked with ‘+’ exist, but messaging 3.0 ignores those conditions.

Codes marked with ‘*’ are also returned by GET /users/* where “sender” means the viewer (the logged-in member) and “receiver” means the profile they are trying to access. In addition GET /users/* can also return the following fail codes:

  • 80061 - the receiver is hidden (not searchable)
  • 80062 - the receiver is new (not yet approved)
  • 80063 - the receiver has been rejected (by Member Services)
  • 80064 - the receiver is inaccessible for other, undocumented reasons
  • 80065 - the receiver is inaccessible for an unknown reason (this should never happen)