Error Codes

Our Client libraries can raise exceptions for many reasons, such as a failed request, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

A Partner PRIVO Platform integration might have to deal with errors at some point when making API requests. These errors fall into a few major categories:

  • Content Error - These errors occur because the content in the API request was invalid in some way. They return an HTTP response with a 4xx error code. For example, the API servers might return a '401' if an invalid API key was provided, or a '400' if a required parameter was missing.
  • Network Error - These errors occur as a result of intermittent communication problems between the Client and Server. They return low-level errors, like socket or timeout exceptions. For example, a Client might time out while trying to read from PRIVO's Servers, or an API response might never be received because a connection terminates prematurely. NOTE: A network error wouldn't necessarily have otherwise been a successful request. It can also be another type of error that's been cloaked by an intermittent problem.
  • Server Error - These errors occur because of a problem on PRIVO's Servers. Server errors return an HTTP response with a 5xx error code. PRIVO works to make these errors as rare as possible, but integrations should have a plan to handle them when they do arise.

PRIVO uses HTTP response status codes to indicate the success or failure of Partner API requests. When a request fails, the Platform returns an error using the appropriate status code. In general, there are 4 status code ranges you can expect.

All methods should return valid HTTP status codes.

  • 200 - Ok - Everything worked as expected. Good Job!

  • 201 - Created - Methods that create records should return this code on success.

  • 208 - Already Reported - For example, this will show when a parent registers a second child.

  • 302 - Found - URL redirection was successful.

  • 400 - Bad Request - Returned if the incoming data parsing failed, or if the JSON was semantically invalid.

  • 401 - Unauthorized - Request needs proper authorization.

  • 403 - Forbidden - Provided authorization is insufficient.

  • 404 - Not Found - The requested resource doesn't exist.

  • 429 - Too Many Requests - Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

  • 5xx - Server Errors - Something went wrong on PRIVO's end (these are very rare).

    In addition, all responses will have a standard wrapper that indicates an more detailed information on the operation.

Expired Token Error Response:

{
          "error": "invalid_token",
          "error_description": "Invalid access token: eyJhbGciOiJSUzIi.......3gZthv7Y"
}

Response Wrapper :

{
  "message": "Ok", //detailed status message
  "status": "success", //success or fail
  "entity": [
    /* the actual data returned by the operation; may be scalar or array, depending on the method */
  ],
  "validationErrors": [
    /* any errors on the inputs */
  ],
  "resultCount": 0, /* if entity is a collection, number of objects in the collection */
  "totalCount": 0/* total number of objects matching the request, if entity is 
                    a collection, in order to support paging */
}