Error Reasons

Error Response

All Sprinque API errors will be of the below 2 formats.

  1. When the known error from the below list has occurred, Sprinque will return the below error code snippet
  ”trace_id”: 12345,
  “error_code”: “auth-declined”,
  “errors”: {”AuthDeclinedError”: [”Charge authorization hold declined.”]}
  1. When an unknown error occurs, Sprinque will return the below error code snippet
  “trace_id”: 12345,
  “error_code”: “sprinque-error”,
  “errors”: {”SprinqueError”: [”Something bad happened. Try later.”]

The complete list of errors can be found below.

HTTP Error Codes

Sprinque 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 given the information provided
  • Codes in the 5xx range indicate an error with Sprinque's servers

4xx errors should be handled programmatically. We recommend writing code that gracefully handles all possible API exceptions. The possible 4xx errors Sprinque returned are below.

400 Bad RequestRequest sent to Sprinque is incorrect or corrupt, and the server receiving the request can't understand it.

Recommended fix - Try making sure all required parameters are present and are sent in the right format.
401 UnauthorizedWhen the Sprinque API key from the merchant control center is not present along with the request, is incorrect or has expired.

Recommended fix - Use the latest API key for that environment or regenerate a new one.
403 ForbiddenThe API key used in the request does not have the right permissions or is inactive.

Recommended fix - Use the latest API key for that environment or regenerate a new one.
409 ConflictThe request could not be processed because of a conflict in the request.

Recommended fix - Ensure it is not a duplicate request and try again.
422 Unprocessable EntityThe server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions

Recommended fix - Use the error messages returned for the exact reason of failure and mitigate it.
429 Too Many RequestsThe user has sent too many requests in a given amount of time.

Recommended fix - Back off for a fixed period of time before trying again.
500 Internal Server ErrorThe Sprinque server encountered an unexpected condition that prevented it from fulfilling the request.

Recommended fix - Contact Sprinque support or retry after some time.
504 Gateway Time-OutThis indicates that the server while acting as a gateway or proxy, did not get a response in time from the upstream server that it needed in order to complete the request.

Recommended fix - Contact Sprinque support or retry after some time.

Detailed List of Errors

Along with the conventional HTTP errors, below is the breakdown of the 4xx errors that Sprinque supports for the various API calls.

Validation Errors

HTTP Response CodeError CodeError Message
400missing-and-invalid-fieldThe format of a field does not match the required input format or required fields are missing.
404resource-not-foundCould not find the resource(s) specified in the request.

API Key Errors

HTTP Response CodeError CodeError Message
401api-key-not-specifiedAPI key is a required field.
401api-key-invalidInvalid API key.
401api-key-inactiveInactive API key.

Buyer Onboarding Errors

HTTP Response CodeError CodeError Message
409duplicate-businessBusiness with the same name or registration number is already registered.
409duplicate-userUser with the same email has already registered.

Transaction Processing Errors

HTTP Response CodeError CodeError Message
422auth-credit-exceededThe buyer has exceeded their available credit limit.
403auth-buyer-under-reviewThe buyer is still under review.
403auth-buyer blockedThe buyer has been blocked.
403auth-buyer-inactiveThe buyer is inactive.
403auth-buyer-blockedThe buyer is blocked.
403auth-credit-not-foundThis can happen when you're using the wrong API key vs buyer_id
404credit-qualification-not-foundCan not find credit qualification. API key might be wrong or not match the environment
409auth-duplicate-requestDuplicate request for merchant_order_id.
403auth-credit-rejectedRejected for credit.
404auth-buyer-not-foundbuyer_id not found.
422auth-credit-pendingCredit limit for this buyer has not approved yet
422auth-credit-manual-reviewThis buyer is under manual review.
422auth-overdue-invoice-exceeded-60-daysOrder is blocked because you have invoice(s) 60 days past due, please pay it/them first.
409authorized-order-existsOrder with this merchant_order_id is already authorized
422auth-amount-exceededAuthorized amount is more the default setting
409auth-currency-doesnt-match-orderCurrency doesn't match order currency (in case of multiple invoices per order)
404payment-account-collection-not-foundThis might happen in case of misconfiguration of the merchant account on the Sprinqiue side.
422buyer-not-eligible-payment-termsThis business is not eligible for the selected payment terms
422does-not-belongs-to-buyerThe user email does not belongs to buyer organisation
404void-transaction-not-foundtransaction_id not found.
422void-capturedThe transaction has already been captured or refunded.
409void-duplicate-pending-transactionTransaction is already cancelled.
403capture-credit-excededCapture exceeds the available credit limit.
422capture-voidedThis transaction has already been voided.
404capture-transaction-not-foundtransaction_id not found.
403refund-exceededThe total amount of credit notes exceeds the invoice amount.
403refund-exceededThe credit note cannot have a higher amount than the invoice.
404refund-transaction-not-foundtransaction_id not found.
422refund-currency-mismatchThe credit note's currency must be the same as the invoice.
422refund-voidedThis transaction has already been voided.
422refund-uncapturedThis transaction has not yet been captured.