API Error Codes

Overview

The SPRL REST APIs return standard HTTP status codes together with SPRL-specific response codes and error flags. These responses help developers quickly identify the cause of a failed request and implement appropriate error handling within their applications.

Each API response includes an HTTP status code, an SPRL response code, and, where applicable, an error flag that provides additional information about the failure.

Response Codes

The following table describes the standard response codes returned by SPRL APIs.

SPRL Code	HTTP Status	Mode	Response Field	Description
100	200	success	data	Request processed successfully.
101	401	failed	message	Authentication failed. Invalid or missing API credentials.
102	422	failed	errors	Parameter validation failed. Check the input fields.
103	403	failed	error	SPRL account is restricted (temporary or permanent block).
104	400	failed	errors	Insufficient wallet balance. Recharge required.
105	500	failed	message	Unexpected server error. Please try again later.
129	429	failed	errors	API usage limit exceeded (daily, monthly, or total).

Error Flag Reference

Error flags provide machine-readable identifiers that allow your application to detect specific failure conditions and respond accordingly.

Category	Flag	Type	Description
Account	ACCOUNT_PERMANENT_BLOCKED	account_restricted	The SPRL account has been permanently blocked.
Account	ACCOUNT_TEMP_BLOCKED	account_restricted	The SPRL account has been temporarily restricted.
Billing	INSUFFICIENT_BALANCE	billing_error	The wallet balance is insufficient to process the request.
Rate Limit	DAILY_LIMIT_REACHED	rate_limit_exceeded	The daily API usage limit has been exceeded.
Rate Limit	MONTHLY_LIMIT_REACHED	rate_limit_exceeded	The monthly API usage limit has been exceeded.
Rate Limit	TOTAL_LIMIT_REACHED	rate_limit_exceeded	The total API usage limit has been exceeded.
Validation	INVALID_PARAMETER	validation_error	One or more request parameters are invalid.
Authentication	INVALID_CREDENTIALS	auth_error	API credentials are missing or invalid.
Server	UNEXPECTED_ERROR	server_error	An unexpected internal server error occurred.

How to Handle API Errors

Check the HTTP status code returned by the API.
Review the SPRL response code to identify the result.
Read the returned response field (message, error, or errors) for additional details.
If an error flag is returned, use it within your application to perform appropriate error handling.
Correct the issue and submit the request again if applicable.

Best Practices

Always validate user input before sending API requests.
Handle all documented HTTP status codes within your application.
Use error flags for programmatic decision making instead of relying only on error messages.
Log failed requests to simplify debugging and support.
Implement retry logic only for temporary failures such as rate limits or unexpected server errors.

Frequently Asked Questions

What is the difference between an HTTP status code and an SPRL response code?

The HTTP status code indicates the result of the HTTP request, while the SPRL response code provides additional application-specific information about the request outcome.

What are error flags used for?

Error flags provide consistent identifiers that allow applications to recognise specific error conditions and automate their handling.

Should my application rely on the error message?

For automated processing, it is recommended to use the returned error flag together with the HTTP status code and SPRL response code.

When should failed requests be retried?

Retry only temporary failures such as rate limiting or unexpected server errors. Authentication, validation, and account-related errors should be corrected before retrying.

Learn More
Continue with the API Best Practices guide to learn how to build secure, reliable, and efficient integrations using the SPRL REST APIs.

Tip
Always log the HTTP status code, SPRL response code, and any returned error flag. This information makes troubleshooting significantly faster during development and production.

Getting Started with SPRL APIs
5 min read

Generate and Manage API Keys
4 min read

Authentication Guide
4 min read

Create Short Links using API
5 min read

QR Code API
5 min read

Server-to-Server Event Tracking API
5 min read