Error Codes

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "Human-readable error description",
    "field": "budget.max",
    "doc_url": "https://soft.house/docs/api/errors#validation_error"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Status	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
429	Rate Limited
500	Internal Server Error

Error Codes

Authentication Errors

Code	Status	Description
invalid_api_key	401	API key is invalid or expired
missing_authorization	401	No Authorization header provided
insufficient_scope	403	Key lacks required permissions

Validation Errors

Code	Status	Description
validation_error	400	Request body validation failed
invalid_parameter	400	Query parameter is invalid
missing_required_field	400	Required field not provided

Resource Errors

Code	Status	Description
not_found	404	Resource does not exist
already_exists	409	Resource with this ID exists
mandate_expired	410	Mandate has expired

Payment Errors

Code	Status	Description
payment_failed	402	Payment could not be processed
insufficient_funds	402	Card has insufficient funds
amount_exceeds_mandate	400	Amount exceeds mandate limit
duplicate_payment	409	Idempotency key already used

Rate Limiting

Code	Status	Description
rate_limited	429	Too many requests

When rate limited, check the Retry-After header for the number of seconds to wait.

Troubleshooting

”invalid_api_key”

1. Verify you’re using the correct key (test vs live)
2. Check that the key hasn’t been revoked
3. Ensure the Authorization header format is Bearer sk_test_...

”rate_limited”

1. Implement exponential backoff
2. Cache responses where possible
3. Contact us to increase your rate limits

”mandate_expired”

1. Create a new mandate before retrying
2. Consider using longer TTL values
3. Implement mandate renewal logic in your application