Spreedly API response codes

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>

Error response

Name	Description
`key`	`errors.access_denied`
`message`	Human readable explanation of error

Potential issues

Cause	Resolution
No HTTP basic authentication was specified.	Be sure to pass in your API call credentials using HTTP basic authentication headers
The environment key or access secret used to authenticate are incorrect.	Make sure to verify and update these values
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://developer.spreedly.com/docs/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://developer.spreedly.com/docs/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	Be sure to only use the Spreedly test gateway with test payment methods and data only

404 Not found

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.

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 408 Request Timeout

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 408 Request Timeout

Potential issues

Cause	Resolution
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	Check Spreedly status page or submit a request with Spreedly Support
There was a problem with the gateway’s response to Spreedly	Submit a request with Spreedly Support

429 Too many requests

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

Rate-limited endpoints

Endpoint	Path	Rate limit
List all transactions	`/v1/transactions.<format>`	30 requests per minute, per environment
Create a payment method	`POST /v1/payment_methods.<format>`	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>`	30 requests per minute, per environment
List certificates	`GET /v1/certificates.<format>`	30 requests per minute, per environment
Create a certificate	`POST /v1/certificates.<format>`	30 requests per minute, per environment
Generate a certificate	`POST /v1/certificates/generate.<format>`	30 requests per minute, per environment
Update certificate	`PUT /v1/certificates/<certificate_token>.<format>`	30 requests per minute, per environment

503 Service unavailable

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.