An API call’s HTTP response code can indicate an error state or some other degradation of service. See the following response codes and corresponding response bodies for common causes.
401 Access denied
The specified environment key and access secret do not exist, do not authenticate, or are not authorized to perform the given action. The request should not be retried without adding or modifying the authentication header.
GET /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 401 Access denied
{
"errors": [
{
"key": "errors.access_denied",
"message": "Unable to authenticate using the given environment_key and access_token. Please check your credentials."
}
]
}
GET /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 401 Access denied
<errors>
<error key="errors.access_denied">Unable to authenticate using the given environment_key and access_token. Please check your credentials.</error>
</errors>
The access secret does not have the permissions necessary to access the environment or perform the specific action.
Be sure to generate an access secret for use in your application
402 Account inactive
The requested action requires an active and paid Spreedly account. The request should not be retried without first upgrading to a paid plan.
POST /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "stripe",
"login": "your Stripe API secret"
}
}
HTTPS/1.1 402 Payment required
{
"errors": [
{
"key": "errors.account_inactive",
"message": "Your environment (SJvv22RySSCgEeMoANtJ2ZOvQCC) has not been activated for real transactions with real payment methods. If you're using a Test Gateway you can *ONLY* use Test payment methods - ( https://docs.spreedly.com/test-data). All other credit card numbers are considered real credit cards; real credit cards are not allowed when using a Test Gateway."
}
]
}
POST /v1/gateways.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
<gateway>
<gateway_type>stripe</gateway_type>
<login>your api secret key</login>
</gateway>
HTTPS/1.1 402 Payment required
<errors>
<error key="errors.account_inactive">Your environment (SJvv22RySSCgEeMoANtJ2ZOvQCC) has not been activated for real transactions with real payment methods. If you're using a Test Gateway you can *ONLY* use Test payment methods - ( https://docs.spreedly.com/test-data). All other credit card numbers are considered real credit cards; real credit cards are not allowed when using a Test Gateway.</error>
</errors>
Error response
Name
Description
key
errors.account_inactive
message
Human readable explanation of error
Potential issues
Cause
Resolution
The organization tied to the environment being accessed is not on a paid plan
Sign up for a paid plan
The operation used a real payment method or production gateway during a test operation
The requested items was not found, and the request should not be retried.
GET /v1/gateways/bad-token.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 404 Not found
{
"errors": [
{
"key": "errors.gateway_not_found",
"message": "Unable to find the specified gateway."
}
]
}
GET /v1/gateways/bad-token.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 404 Not found
<errors>
<error key="errors.gateway_not_found">Unable to find the specified gateway.</error>
</errors>
Error response
Name
Description
key
error.<item>_not_found where item is the type of record being requested (gateway, transaction, etc.)
message
Human readable explanation of error
Potential issues
Cause
Resolution
The specified token represents an item (gateway, payment method etc.) that does not exist in the authenticated environment.
Specify the correct environment key in the API call
The requested item does not exist (in any environment)
Retry with an item that exists
406 Not acceptable
The request includes an invalid or unsupported Accept header. Ensure that the headers are valid before trying again. Otherwise, the request was blocked by a security rule and should not be retried.
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 406 Not acceptable
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 406 Not acceptable
Potential issues
Cause
Resolution
The request included an invalid or unsupported Accept header
Ensure your accept header is one of */*, application/json, or application/xml
The request was flagged as a security risk
Make sure the request does not contain malformed or malicious content
The request was sent to a restricted endpoint
Make sure the request is sent to a valid endpoint
The request was received from a restricted IP address
If all requests from this IP address result in a 406 response, submit an issue to Spreedly support
408 Request timeout
The external service, such as a gateway, did not respond within the request timeout period or experienced a connection error. In these situations, it is impossible to determine the final state of the transaction and the transaction state will be set to gateway_processing_result_unknown. This is a fundamental issue in distributed systems - if a reply isn’t received, the result can’t be known.
If you receive a 408 for a transaction where actual money is changing hands (like a purchase or a capture), check with the third party (gateway, receiver, etc.) to determine what the real result was before retrying.
The gateway or other external service did not response in a timely manner
Check the gateway to determine the final status of the transaction before attempting a retry
There was a connection error communicating with the external service
Check the gateway to determine the final status of the transaction before attempting a retry
415 Unsupported media type
The request includes an invalid or unsupported Content-Type header. Ensure that the headers are valid before trying again.
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 415 Unsupported Media Type
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 415 Unsupported Media Type
Potential issues
Cause
Resolution
The request included an invalid or unsupported Content-Type header
Ensure your content-type header is application/json or application/xml
422 Request not processed
The request could not be processed. An error message with more detail may be present in the response. See the list of potential issues for known cases.
PUT /v1/gateways/<gateway_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"gateway": {
"gateway_type": "stripe"
}
}
HTTPS/1.1 422 Unprocessable Entity
{
"errors": [
{
"message": "You may not change the gateway_type of a gateway.",
"key": "errors.gateway_gateway_type_cannot_be_changed"
}
]
}
PUT /v1/gateways/<gateway_token>.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
<gateway>
<gateway_type>stripe</gateway_type>
</gateway>
HTTPS/1.1 422 Unprocessable Entity
<errors>
<error key="errors.gateway_gateway_type_cannot_be_changed">You may not change the gateway_type of a gateway.</error>
</errors>
Error response
Name
Description
attribute
The specific field that failed validation
key
errors.<offending_item> a key indicating the type of error experienced
message
Human readable explanation of error
Potential issues
Cause
Resolution
The payment method is redacted, closed, or used
This payment method cannot be used and the request should not be retried. The result in this case will include a full transaction response and token.
The request is not valid
Verify the request matches the format and value types specified in our API reference, correct it and retry
There was difficulty communicating with the gateway
There have been too many API calls against a rate-limited endpoint.
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 429 Too Many Requests
GET /v1/transactions.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
HTTPS/1.1 429 Too Many Requests
1000 requests per 24 hours, per first-six, last-four, and environment, or 250 requests per 24 hours, per first-eight, last-four, and environment, OR 30 requests per minute and IP address
GET /v1/receivers_options.<format>
30 requests per minute, per environment
GET /v1/receivers.<format>
30 requests per minute, per environment
POST /v1/receivers.<format>
30 requests per minute, per environment, indiscriminate of http or sftp receiver
GET /v1/receivers/<receiver_token>.<format>
30 requests per minute, per environment
UT /v1/receivers/<receiver_token>.<format>
30 requests per minute, per environment
PUT /v1/receivers/<receiver_token>/redact.<format>
Spreedly is temporarily unable to process the request.
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"amount": 100,
"currency_code": "USD"
}
}
HTTPS/1.1 503 Service Unavailable
{
"errors": [
{
"key": "errors.circuit_breaker_open",
"message": "Spreedly detects a payment gateway outage, recommend retrying transaction on a backup gateway",
"gateway_name": "Bogus"
}
]
}
POST /v1/gateways/<gateway_token>/purchase.<format> HTTPS/1.1
Host: core.spreedly.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/<format>
<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>
HTTPS/1.1 503 Service Unavailable
<errors>
<error key="errors.circuit_breaker_open" gateway_name="Bogus">Spreedly detects a payment gateway outage, recommend retrying transaction on a backup gateway</error>
</errors>
Potential issues
Cause
Resolution
There are persistent errors while communicating with the gateway, leading Spreedly to temporarily halt requests to this gateway
Retry the request in 60 seconds, or set up a backup gateway using Recover
Spreedly is experiencing general instability
Check the status page to see if there is a known issue and the expected resolution time
500 level errors
Other 500 level errors, such as 500, 502 and 504, are application errors which indicate that the API cannot handle a request. Please contact Spreedly support regarding specific transactions that receive this response.
