API status and error codes

Below section describes response codes from Client-API in detail.

1. Success Response

HTTP Status	Description
200 OK	For apis with single entity payload, 200 HTTP status OK is expected in case api operation is successful but transaction status { “success“: false/true }. For apis accessed with <async=true>, except validations other errors are wont be added in feedback. It may give an immediate success but may be failing silently in background. For apis with multiple entities to process on payload, 200 HTTP status OK doesn't mean entire batch is processed but partial operation is completed. NB: Its recommended to have webhooks for listening to failures for critical resource creation like claim, account etc.

1. Error Response: getOauth2Token
   1. URL: POST /v1/oauth2/token
   2. Headers: basic auth & Content-Type

HTTP Status Code	Meaning	Resolution Tip	Error Response
400 Bad Request	Wrong values in basic auth.	In headers -Check Username is correct -Check Password is correct	application/json {"error": "invalid_client"}
401 Unauthorized
400 Bad Request	Incorrect JSON	-In payload -check JSON is properly formatted	{"success":false,"messageIds":[],"messages":["SyntaxError: Unexpected token } in JSON at position 389"]}
405 Method Not Allowed	Wrong value of Content-Type in headers	In headers -Check Content-Type is application/x-www-form-urlencoded	No Payload
403 Forbidden	Wrong url	-Check url is misspelt	{"message":"Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter. Authorization header requires 'SignedHeaders' parameter. Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header. Authorization="}

1. Error Response: generic for all apis
   1. URL: POST /v1/{clientId}/
   2. Headers: basic auth & Content-Type
   3. Payload: JSON{}
   4. For generic errors: refer above
   5. For transaction status: response JSON { “success“: false/true }

HTTP Status Code	Meaning	Resolution Tip	Error Response
400 Bad Request	Wrong values in JSON payload	-Check mandatory fields are part of payload	{"messages":["body/[<claimId>] should have required property '<field>'"],"messageIds":[],"success":false}
400 Bad Request	Wrong data type for individual field	-Check data type for fields mentioned in error response, rectify and retry	{"messages":["body/['ENTITYID'].currency should be string","body/['ENTITYID'].currency should be string"],"messageIds":[],"success":false}
401 Unauthorized	Missing Authorization token	In headers -Check Authorization	{ "message": "Unauthorized" }
403 Forbidden	Invalid Authorization token	In headers -Check Authorization is valid -Re-request for Oauth2 token	{ "Message": "User is not authorized to access this resource with an explicit deny" }
403 Forbidden	Wrong URL	In URL -check url is correct	{"message":"Authorization header requires 'Credential' parameter. Authorization header requires 'Signature' parameter. Authorization header requires 'SignedHeaders' parameter. Authorization header requires existence of either a 'X-Amz-Date' or a 'Date' header. Authorization="}
413 Request Entity Too Large	Large Payload	In Payload -minimize json payload if url supports multi-entities	{"success":false,"messageIds":[],"messages":["request entity too large"]}
500 Internal Server Error	Service is down	-Retry with same payload after sometime -Alert to Receeve Account Manager
502 Bad Gateway	Service is unavailable	-Never retry -Alert to Receeve Account Manager	{"message": "Internal server error"}
503 Timeout	Service is timing out	-Retry with less payload entries -Alert to Receeve Account Manager on recurrence

1. Error Response: Processing errors (sync=true)

a. For apis, while doing processing payload internally may result in errors due to duplicate, invalid or non-existent entityIds.

b. HTTP status will be 200 OK, but response follow the format as below in case of single/multiple business errors,

{
  "<ENTITY_ID>": {
    "messages": [
      "[<ERROR_CODE1>] ERROR_NAME1: ERROR_DESCRIPTION1",
      "[<ERROR_CODE2>] ERROR_NAME2: ERROR_DESCRIPTION2"
    ],
    "messageIds": [],
    "success": false
  }
}

c. Sample error response

{
  "DV_ACCOUNT_REFERENCE_20230817": {
    "messages": [
      "[4007] AlreadyDefinedLedgerEntryError: Already defined ledger entry"
    ],
    "messageIds": [],
    "success": false
  }
}

Code	Error Name	Resolution Tip
4001	ResourceNotFoundError	-Inspect any of the entitIyds in the payload like claimId, accountRef, ledgerEntry. This may be invalid ids or in invalid state of processing like DELETED or RESOLVED. -Retry after correcting payload.
4002	ParameterInputError	-Inspect the payload for entityids which are non-existent in receeve system due to previous operations. -Retry after correcting payload.
4003	AccountNotFoundError	-Inspect accountRef/accountId is valid and retry after correction
4005	DebtorNotFoundError	-Inspect debtorRef or debtor is valid and retry after correction
4006	LedgerEntryNotFoundError	-Inspect ledgerEntryReference is valid and retry after correction
4007	AlreadyDefinedLedgerEntryError	-Inspect ledgerEntryReference is valid and retry after correction
4008	ClaimNotFoundError	-Inspect claimRef/claimId is valid and retry after correction
4010	ClaimContextNotFoundError	-Inspect claimRef/claimId is valid and retry after correction
4019	InvalidAccountClaimError	-Inspect account belongs to the claimRef or not and retry after correction
4020	DiscountNotFoundError	-Inspect discountId is valid and retry after correction
4021	AccountDiscountMismatchError	-Inspect account belongs to the discountId or not and retry after correction
4022	InvalidPaymentMatchError	-Payment matching strategy is invalid for the account
4023	InvalidProlongationError	-Invalid prolongation details to the account.
4024	ProlongationDisabledError	-Account is disabled with prolongation criteria being called.
4025	InvalidInstalmentError	-Payments totalling to due amount needs to be corrected.
4026	DuplicateAccountRestructureError	-Restructuring is already available for the account
4028	DeletedClaimStatusError	-Claim is already deleted.
4030	StrategyNotFoundError	-Inspect strategyId is valid and retry after correction
6000	ConfigurationError	-Account has to activated with particular configuration. -Contact receeve customer-support or account management for further help. -Dont retry until issue is resolved.
7000	InternalError	-Receeve has internal service availability issue and has to be notified -Contact receeve customer-support or account management for further help. -Dont retry until issue is resolved.