API Reference Guide
Complete Developer Guide to Onemoney APIs 



All Onemoney APIs are completely RESTful. All responses are returned in JSON.
The financial data returned as part of responses to data requests are in encrypted XML format. The data is stored as one of the attributes in the JSON response structure.
Onemoney APIs can be used in one of two modes, Test and Live. Visit our developer portal to receive API keys to try out our APIs.
Click here to understand the various error codes
Onemoney API Gateway URL
https://api-sandbox.onemoney.in/
Please include this before each API endpoint to make API calls
API Authorisation
As a FIU
Digital Signatures
Digital signature generation and validation is currently switched off on our sandbox, for all API-based exchanges between the FIU and the AA. Enabling this involves the exchange of public key information. The same can be done in production-mode through the Central Registry hosted by Sahamati. If you are interested in more information on this, please write to helpdesk@onemoney.in
When you access Onemoney APIs, you are authorized based on an FIU ID (Financial Information User ID) and an API key issued to you by us, using the developer portal.
The API key can be generated by you as part of the Settings > API Keys function.
The API key needs to be placed in the header of each API request, as shown below:

Conversely, all APIs implemented by you, such as Post Consent Notification and Post /FI/Notification, that are called by Onemoney, also need to be authorized by you based on an API key issued by you to us.
While using our APIs in test mode, this API key too can be generated by the developer portal through Settings > API Keys function.
As a FIP
[Coming Soon…]
Error Codes and Details
All successful responses are returned with HTTP Status code 200. In case of failure, Onemoney API returns a JSON error response with the parameters that detail the reason for the failure.
Error Response
The error response contains errorcode
and timestamp
parameters that help you diagnose and solve the error.
To understand more about error codes, refer to the Error Codes section.
Please find the one sample error response below:
{
“timestamp”: “2020-06-28T16:48:19.112Z”,
“errorCode”: “InvalidRequest”
}
Error | object | The error object |
timestamp | string($date-time) | Time of the response received |
errorcode | string | Type of the error |
Error Codes
Onemoney aims to make every data transaction successful for its customers. However, in the financial ecosystem errors might still occur because of intermittent communication and technical issues at multiple hops. Hence, it becomes critical for businesses to identify the status of API response and the reason that caused the error. In short, you can identify the reason why any error occurred. This enables you to minimize or fix errors.
Understanding the Error codes
Onemoney AA uses conventional HTTP response codes to indicate the success or failure of an API request.
In general:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate an error that failed because of the information provided (e.g., a required parameter was omitted, a transaction failed, etc.).
- Codes in the 5xx range indicate an error with Onemoney AA servers (these are rare).
Note: Some 4xx errors that could be handled programmatically (e.g., account linking failed etc) are explained along with an error code that briefly reports the error details.
Understanding the Error Response
Let us take an example where error occurred when raising a consent.
Sample error response:
{
“timestamp”: “2020-06-28T16:48:19.112Z”,
“errorCode”: “InvalidRequest”
}
By looking at the errorcode of the api response, it can be understood that the response is a failure(some error occured) because of using an invalid request. So, this clearly tells the user to go and enter the required request parameters mentioned against the APIs.
Related Information
For the list of common error codes and a quick resolution, you can refer to Common Error Codes.
For API specific error codes and their quick resolution, refer to the API specific Error Codes section.
Common Error Codes
All the possible values for the errorcode parameter in the error response which are common for all the APIs along with their explanation and the next best action to be taken are shown below.
Https Status Code | Error code | Explanation | Next Steps |
---|---|---|---|
400 | Bad Request | This errorcode occurs as a response to the API call made when a required parameter is missing or an improper request body is sent in the payload of API. | Refer to the Request body table given for the API to check for any missing parameter and add it in the payload of API for making a valid API call. |
400 | Bad request headers | This errorcode occurs as a response to the API call made, when request headers are unavailable | Refer to the Request body header table given for the API to check for any missing header parameter and add it in the payload of API for making a valid API call |
400 | Invalid URI | This errorcode occurs as a response to the API call made when the API call couldn"t parse the specified URI/Endpoint | Check the URI/endpoints given against the API for which the response has occurred and replace it with a valid endpoint. |
401 | Invalid Session ID | This errorcode occurs as a response to the API call made, if the entered sessionId is expired or is not a valid entry | Use Initialize session API for a valid session |
401 | Invalid apiKey | This errorcode occurs as a response to the API call made,if the entered apiKey parameter as a header of API is either incorrect or invalid | Use the client_api_key parameter given to you. |
401 | Unauthenticated | This errorcode occurs as a response to the API call made, when the session is invalid or user not logged in. | FIU has to ask the customer to login or use the initialise session API to get a valid session |
403 | AccessDenied | This errorcode occurs as a response to the API call made, in case when the Web server forbids the user from accessing the API | To resolve the issue contact us at support@onemoney.in |
404 | NoSuchVersion | This errorcode occurs as a response to the API call made, when the ver parameter value in the request body is incorrect | To resolve the issue change the version to the latest or contact us at support@onemoney.in |
405 | MethodNotAllowed | This errorcode occurs as a response to the API call made,when the specified API method used is not allowed against the API used | Refer to the specific API in https://www.onemoney.in/docs/api/ to use the method which is allowed to make the API call |
410 | OTP_VERIFIED_ALREADY | This errorcode occurs as a response to the API call made, when the otp is already verified. | Verification not required, please proceed to the next step. |
410 | OTP_FAILED_TOO_MANY_ATTEMPT | This errorcode occurs as a response to the API call made, when the otp requested has already reached the final state(verified,expired, failed after too many attempts) | Try after sometime to request OTP again. |
411 | MissingContentLength | This errorcode occurs as a response to the API call made, when the header of the request body doesn’t contain content-length | Resolve the issue by adding content-length as a header parameter and assigning value as application-json |
412 | PreconditionFailed | This errorcode occurs as a response to the API call made, when one of the pre-conditions mentioned for the API is not full-filled. | Refer to https://www.onemoney.in/docs/api/ to check for the validations and pre-conditions if any of the request body parameters of the specific API for which this error has occurred. |
415 | UnsupportedMediaType | This errorcode occurs as a response to the API call made, when the payload is not a json structure. | Please change the payload to json file |
422 | INVALID_OTP | This errorcode occurs as a response to the API call made, when the otp is either incorrectly entered or invalid | Resolve the issue by requesting OTP again. |
429 | LimitExceeded | This errorcode occurs as a response to the API call made, when AA exceeds the API call limit accepted by FIP. | To resolve the issue contact us at support@onemoney.in |
500 | Internal Error | This errorcode occurs as a response to the API call made, when there is an internal error with Onemoney | To resolve the issue try after sometime or contact us at support@onemoney.in |
502 | BadGateway | This errorcode occurs as a response to the API call made, when there is no valid response from the Onemoney web server | To resolve the issue try after sometime or contact us at support@onemoney.in |
503 | SERVICE_UNAVAILABLE | This errorcode occurs as a response to the API call made in two cases, One being error connecting to the sms operator and the other being not being able to connect to FIU/FIP | To resolve the issue try after sometime or contact us at support@onemoney.in |
503 | ERR_CONNECT_SERVICE | This errorcode occurs as a response to the API call made, when the Onemoney server is not able to connect to SQS | To resolve the issue try after sometime or contact us at support@onemoney.in |
504 | GATEWAY_TIMEOUT | This errorcode occurs as a response to the API call made, when there is no response from the Onemoney server on time | To resolve the issue try after sometime or contact us at support@onemoney.in |
520 | ERR_UNKNOWN | This errorcode occurs as a response to the API call made, due to a variety of unexpected reasons. | To resolve the issue try it after sometime or contact us at support@onemoney.in |
The above error codes are common errors which you might come across all of the APIs and in case the error occurred is specific to API, please refer to API specific Error Codes.
In case you didn’t find a resolution with the above APIs, please reach out to us at helpdesk@onemoney.in
API Specific Error Codes
API Name | HttpStatusCode | Error Title | Explanation | Next Steps |
---|---|---|---|---|
Place a consent Request API | 400 | InvalidConsentPurpose | This errorcode occurs as a response to the API call made, for the case when the purpose parameter array has an invalid or incorrect value. | Refer purpose table to add correct value of purpose array parameter. |
Place a consent Request API | 400 | InvalidRequest | This errorcode occurs as a response to the API call made, when one or more parameters are missing in the request body of the API. | Refer to the Request body table given for the API to check for any missing parameter and add it in the payload of API for making a valid API call. |
Get Status of consent request API | 400 | InvalidConsentHandle | This errorcode occurs as a response to the API call made, when consenthandle parameter in the request body of the API is either incorrectly entered or invalid | Use Place a consent Request API to get a valid consenthandle parameter as a response. |
Fetch the consent artefact | 400 | InvalidConsentId | This errorcode occurs as a response to the API call made, when the consentId parameter in the request body of the API is either incorrectly entered or invalid | Use Get Status of Consent Request to get a valid consentId as a response parameter. |
Place a Data request API | 400 | InvalidConsentId | This errorcode occurs as a response to the API call made, when the consentId parameter in the request body of the API is either incorrectly entered or invalid | Use Get Status of Consent Request to get a valid consentId as a response parameter. |
Place a Data request API | 400 | InvalidKey | This errorcode occurs as a response to the API call made, when one of the many parameters under keymaterials array is either incorrectly entered or invalid | Use click here option available in the instructions of Request Data API to generate and enter valid parameters under keymaterials array in Place a Data Request API |
Place a Data request API | 400 | InvalidDateRange | This errorcode occurs as a response to the API call made, when the FIDataRange array mentioned in the consent details doesn’t match in Request Consent API. | Use Fetch the Consent Artefact API against the consent raised to get a valid Date range from the array parameters of FIDataRange |
Place a Data request API | 403 | ConsentExpired | This errorcode occurs as a response to the API call made, when the consent raised has expired | Consent has to be raised again to request data, so use Place a consent Request API and Get Status of Consent Request to create and approve consent and use the parameters from Fetch the Consent Artefact API to make a valid Request Data API call. |
Place a Data request API | 403 | ConsentRevoked | This errorcode occurs as a response to the API call made, when the consent is revoked during FI request operation. | FIU has to check with his customer and if revoked, has to place a new consent request using |
Place a Data request API | 403 | ConsentPaused | This errorcode occurs as a response to the API call made, when the consent is paused for now. | FIU has to notify the user about the error, if required request the user to resume. |
Place a Data request API | 404 | ExpiredKeyMaterial | This errorcode occurs as a response to the API call made, when the DHpublic key parameter in Request data API has expired. | Set theDHpublic key parameter in the request body of the API to a latest expiry date. |
Fetch Data API | 400 | InvalidConsentId | This errorcode occurs as a response to the API call made, when the consentId parameter sent in the request body is either incorrectly or invalid | Use Get Status of Consent Request to get a valid consentId as a response parameter. |
Fetch Data API | 400 | InvalidSessionId | This errorcode occurs as a response to the API call made, when the SessionId parameter sent as a request is either incorrectly or invalid | Use Request Data API to get a valid SessionId as a response parameter. |
Fetch Data API | 403 | DataFetchRequestInProgress | This errorcode occurs as a response to the API call made, when FI Data fetch request is already in operation and another FI data fetch request API call is made for the same consentId | FIU has to wait for Onemoney to call the post FIU notification (data readiness notifications) and make the API call after. |
Fetch Data API | 404 | NoDataFound | This errorcode occurs as a response to the API call made, when there is no data found for the requested data using Request Data API | Use the test data created to get data. |
Fetch Data API | 410 | DataGone | This errorcode occurs as a response to the API call made, when the data is purged from the server(occurs only when FIU fetches the data | FIU has to check in their server for data, if not found has to raise a new consent using Place a consent Request API , use Get Status of Consent Request and Place a Data Request API to get data |