API Conventions

Errors

Like any good RESTful service, your first clue to how your API request went is the HTTP status code. If it's something other than 200 OK, something went awry. While some such responses might be informational (300s), most will be errors, either yours (400s) or ours (500s).

Here are some common HTTP error codes you might see in your responses:

400 Bad Request
Something was wrong with your request. More than likely, you passed in a bad parameter value.
401 Unauthorized
The request you made requires authorization yet no credentials were provided. Likely, you forgot an Authorization header for a resource that requires it.
403 Forbidden
Your request was understood by the server and rejected it. This is common when you request sensitive resources insecurely (eg, not using HTTPS to access user-sensitive data), or if your authorization credentials don’t match up with data your are trying to access - for example you supply Lender credentials to access private data for a Partner.
404 Not Found
We couldn't find the resource you requested. In other words, your URI was probably incorrect. It may be the case of a non-existent resource name or a bad ID parameter.
405 Method Not Allowed
The resource you requested is valid, but it doesn't support the HTTP method you used to access it. For example, you may have sent a POST request for a resource only available by a GET request.
500 Internal Server Error
This one's our fault. Kindly post to the forum if you see this so we can look into it.
503 Service Unavailable
The Kiva servers are overloaded or down for maintenance. In the latter case, we'll typically add a Retry-After header that lets you know when things might be back up.

HTTP status codes are good for web tools, but fancy software programs and humans deserve more. That's why every error response will also have a simple content body with more detail on your error. We provide a computer-friendly code and a human-friendly message both serialized in the response format you specified. If you made a GET request for this URI:

http://api.kivaws.org/v1/gobbledygook.json

here's what you'd get:

{ "code":"org.kiva.InvalidResource" "message":"We could’t find the resource you were trying to access. Check your URL to confirm it’s a valid API endpoint. Check your HTTP request method (GET, POST, etc.) to make sure it is supported by the corresponding endpoint." }

XML responses look similar with a root element of error. Test responses in HTML will also show you the HTTP status code in the HTML response. Errors for a feed format (RSS, ATOM, etc.) will default to HTML output.

The message value in errors is our attempt to help you resolve the problem with your call. For instance, if you pass in a bad parameter, we'll tell you which parameter didn't make the cut. The code value is a unique string in reverse-domain notation that your application can test against to get finer granularity on what happened outside of the HTTP status. You may choose to use this code to pass on a localized error message to your users in certain conditions. Here's a list of some of the more common codes:

org.kiva.InvalidResource
The URI in your request was malformed so we don't know what resources you're looking for. Perhaps the API endpoint you want to call doesn't exist or you might have a poorly formed parameter in the URI that is causing problems.
org.kiva.MalformedParameter
You passed in a value that was outside the bounds of what we allow for a particular parameter.
org.kiva.InvalidIdentifier
You passed in an value for a identifier parameter that does not correspond to anything we know about. For example, '111' is not a valid ID for a loan.
org.kiva.HttpsRequired
You are trying to use HTTP to access a resource that is only available via HTTPS.
org.kiva.ServerMaintenance
We're upgrading our servers to make Kiva better and the Kiva API is not available at this time. Try again later.
Kiva
  • © 2009 - 2014 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.